# Troubleshooting

> Diagnose Tokenade with tokenade healthcheck: what each check id means, the exact messages your agent sees when Tokenade pauses, and how to fix each case.

Source: https://tokenade.net/en/docs/troubleshooting · Updated: 2026-10-16

When savings stay at zero or your agent mentions a Tokenade message, start with one command:

```bash
tokenade healthcheck
```

It checks the binary, every agent's hooks and the local stores, prints one row per check, and exits with code `1` if any row is a failure. `tokenade health` and `tokenade doctor` are aliases. Add `--json` to get a structured object (`version`, `failures`, `ok`, `checks[]`) where each check has a stable `id`, handy in scripts:

```bash
tokenade healthcheck --json | jq '.checks[] | select(.id == "hook_installed")'
```

Rows marked `OK` passed, `--` are information only, and `!!` are failures.

## Healthcheck rows and their fixes

| id | What a failure or warning means | Fix |
|---|---|---|
| `binary` | Shows which `tokenade` runs, and warns when several copies are on your PATH. | Remove the copy you do not want, or put the right one first in PATH. |
| `gain_ledger` | `~/.tokenade/gain.jsonl` is not writable, so no saving is recorded. | Fix ownership or permissions of `~/.tokenade/` (often created by a `sudo` run). |
| `agent_detect` | No AI agent detected for the current directory tree (information). | Run it from a project where you use your agent. |
| `hook_installed` | Claude Code has no Tokenade hooks: never installed, or removed by another tool or an agent update. | `tokenade ensure-hooks` if Tokenade was installed before, otherwise `tokenade install`. |
| `pretool_read` | Tokenade's hooks in Claude Code's settings do not cover file reads, so read optimisation never fires. | `tokenade ensure-hooks`. |
| `hook-integrity` | Some Tokenade hook commands differ from the installed shape. Drift can indicate tampering. | `tokenade install`. |
| `binary_paths` | Agent configs point at a `tokenade` binary that no longer exists, so those hooks are silently dead. | `tokenade install` to rewrite the paths. |
| `hook_binaries_agree` | Your hooks run a different `tokenade` from the one on your PATH. | `tokenade install` from the copy you want to keep. |
| `codex-hook-trust` | Codex has not approved Tokenade's hooks, so they do nothing. | See [Codex hooks not approved](#codex-hooks-not-approved). |
| `claude-workspace-trust` | Claude Code has not trusted the current folder, so in an interactive session it runs no hooks at all. | Accept the trust prompt when Claude Code opens the folder. `claude -p` runs are not affected. |
| `mcp_entry` | An old `tokenade` entry is left in an agent's `mcpServers`; it starts the removed `tokenade mcp` command. | `tokenade install` purges it. |
| `wrapped_mcps` | Third-party MCP servers wrapped by `mcp-wrap` point at a stale Tokenade path. | `tokenade unwrap-mcps && tokenade install`. |
| `stale_mcp_procs` | Tokenade MCP processes are still running an old binary. | Restart your agent. |
| `semantic_model` | The embedding model is not downloaded yet (information). It is fetched once on first `semantic` or `--prompt` use. | Nothing to do. |
| `posix-shell` | Windows only: no `sh`/`bash` found, so shell-command compaction is off. | Install Git for Windows. |
| `web_transport` | `curl` not found; web fetching works but is degraded (information). | Install `curl`. |
| `filter-syntax` | Some compactor files do not parse, so they never fire. | Fix or delete the file named in the detail. |
| `project-filters` | Project-local compactors are waiting for approval (information). | `tokenade trust-filters` (inspect first with `--list`). |
| `ledger-integrity` | Rows of the savings ledger break accounting rules. | `tokenade audit-gains` shows the detail. |
| `disk-footprint` | How much disk Tokenade uses, biggest items first. | `tokenade evict-stale` prunes stale cache rows. |

Other informational rows (plugin activity per agent, levers that never fired, bypass counts) describe how Tokenade is being used and do not need a fix.

## See what the hooks did

```bash
tokenade hooks status     # every installed Claude Code hook
tokenade hooks tail 50    # the last 50 hook events from ~/.tokenade/debug.log (default 20)
```

Both accept `--json`. The debug log is a JSON-lines file: one event per line with `ts`, `component`, `event` and `details`. It is on by default after `tokenade install` (unless you installed with `--no-debug-log`) and rotates at 16 MiB. To log somewhere else, set `TOKENADE_DEBUG_LOG=<path>` where your agent starts.

Hooks never block your agent: if Tokenade fails, the tool call goes through unchanged. To rule Tokenade out while debugging, set `TOKENADE_HOOK_DISABLED=1`, or prefix one command with `tokenade raw`.

## Your agent says Tokenade is paused

Tokenade 2.0 never pauses: there is no licence or quota to check. If your agent relays a notice that starts with `tokenade —` and mentions an account, a licence, billing or tokenade.net being unreachable, that machine still runs a 1.x release. Upgrade it:

```bash
npm i -g @tokenade/cli@latest
```

See [Upgrading from 1.x](https://tokenade.net/en/docs/install#upgrading-from-1x).

## Codex hooks not approved

Codex does not run a hook until you have approved it. `tokenade install` approves the hooks it writes by recording their trust in `~/.codex/config.toml`. If the `codex-hook-trust` row fails, re-apply it:

```bash
tokenade codex-trust
```

It prints `trusted N Codex hook(s) in ~/.codex/config.toml`. You can also approve them from Codex itself with `/hooks`. Until the hooks run, Tokenade's [LLM proxy](https://tokenade.net/en/docs/llm-proxy) covers Codex for output folding, credential scrubbing and the style note; when the hooks do run, nothing is done twice. See [Codex](https://tokenade.net/en/docs/codex).

## Claude Code ignores hooks in a folder

Claude Code runs no hooks in an interactive session opened in a folder whose trust prompt was not accepted. Tokenade's hooks are not special: nothing is compacted there. The `claude-workspace-trust` row points this out; accept the prompt when Claude Code opens the folder.

## `tokenade install` refuses under sudo

```text
✗ running under sudo: this would install into /root, not your own HOME —
  your AI agent would never see the hooks (and everything would LOOK fine).
  Re-run WITHOUT sudo: tokenade install
  (intentional root install: TOKENADE_ALLOW_ROOT=1 tokenade install)
```

Run it as your own user. If you really use your agent as root, set `TOKENADE_ALLOW_ROOT=1`.

## Hooks disappeared after an agent update

Some agent updates or other tools rewrite the settings file. Tokenade checks and repairs its hooks by itself from time to time. To repair now:

```bash
tokenade ensure-hooks --force
```

## Report a bug

If none of this helps, open an issue on [GitHub](https://github.com/pi-infected/tokenade/issues). Include your `tokenade --version`, the output of `tokenade healthcheck`, and the relevant lines of `tokenade hooks tail`; check them for anything private before you paste them.

For background on how Claude Code hooks behave, see [Claude Code hooks](https://tokenade.net/en/articles/claude-code-hooks).

## Related

- [How hooks intercept tool calls](https://tokenade.net/en/docs/hooks)
- [Maintenance commands](https://tokenade.net/en/docs/maintenance)
- [Upgrade and uninstall](https://tokenade.net/en/docs/upgrade-uninstall)
- [Environment variables](https://tokenade.net/en/docs/environment-variables)
