tokenade
GitHubenfr
Install

Troubleshooting

Updated

TL;DR — Run tokenade healthcheck first: every row has a stable id and a fix, and it exits 1 if a check fails. tokenade hooks status and tokenade hooks tail show what the hooks did. Most failures are fixed by tokenade install or tokenade ensure-hooks.

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

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:

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

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

Healthcheck rows and their fixes

idWhat a failure or warning meansFix
binaryShows 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_detectNo AI agent detected for the current directory tree (information).Run it from a project where you use your agent.
hook_installedClaude 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_readTokenade's hooks in Claude Code's settings do not cover file reads, so read optimisation never fires.tokenade ensure-hooks.
hook-integritySome Tokenade hook commands differ from the installed shape. Drift can indicate tampering.tokenade install.
binary_pathsAgent configs point at a tokenade binary that no longer exists, so those hooks are silently dead.tokenade install to rewrite the paths.
hook_binaries_agreeYour hooks run a different tokenade from the one on your PATH.tokenade install from the copy you want to keep.
codex-hook-trustCodex has not approved Tokenade's hooks, so they do nothing.See Codex hooks not approved.
claude-workspace-trustClaude 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_entryAn old tokenade entry is left in an agent's mcpServers; it starts the removed tokenade mcp command.tokenade install purges it.
wrapped_mcpsThird-party MCP servers wrapped by mcp-wrap point at a stale Tokenade path.tokenade unwrap-mcps && tokenade install.
stale_mcp_procsTokenade MCP processes are still running an old binary.Restart your agent.
semantic_modelThe embedding model is not downloaded yet (information). It is fetched once on first semantic or --prompt use.Nothing to do.
posix-shellWindows only: no sh/bash found, so shell-command compaction is off.Install Git for Windows.
web_transportcurl not found; web fetching works but is degraded (information).Install curl.
filter-syntaxSome compactor files do not parse, so they never fire.Fix or delete the file named in the detail.
project-filtersProject-local compactors are waiting for approval (information).tokenade trust-filters (inspect first with --list).
ledger-integrityRows of the savings ledger break accounting rules.tokenade audit-gains shows the detail.
disk-footprintHow 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

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:

npm i -g @tokenade/cli@latest

See Upgrading from 1.x.

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:

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 covers Codex for output folding, credential scrubbing and the style note; when the hooks do run, nothing is done twice. See 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

✗ 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:

tokenade ensure-hooks --force

Report a bug

If none of this helps, open an issue on GitHub. 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.