Docs / Troubleshooting
Troubleshooting
Updated
When savings stay at zero or your agent mentions a Tokenade message, start with one command:
It checks the binary, the license, 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:
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. |
license | No license on this machine, the license no longer verifies, the quota is used up, or tokenade.net has been unreachable for 3+ days. The row prints the same message your agent gets (see below). | Usually tokenade login. |
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. |
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
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.
Tokenade is paused
When Tokenade cannot compact, it does not fail your agent's tool calls. It hands the agent a notice, the agent carries on with its normal tools, and compaction stops on that machine. There are four notices.
Machine not connected.
Fix: run tokenade login in a terminal. See Log in and activate a machine.
License invalid.
Fix: tokenade login. This happens, for example, when a license file was copied from another machine.
Monthly quota used up. The notice starts with:
It then points to the upgrade page (Free plan) or the pay-as-you-save unlock in your dashboard (Pro plan). Compaction resumes on the 1st of the month or as soon as your plan allows more. See pricing.
tokenade.net unreachable for over 3 days.
The pause starts 72 hours after the first failed usage report. Fix: allow HTTPS to https://tokenade.net through your firewall, proxy or DNS filter, then run tokenade healthcheck to retest at once. See What Tokenade sends.
Machine removed from the dashboard (MACHINE_REVOKED)
If you remove a machine from your dashboard at tokenade.net, its next usage report gets an HTTP 403 with MACHINE_REVOKED. Tokenade then deletes the local license and quota cache, and the machine falls back to the "isn't connected" notice above. To use it again, run tokenade login.
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:
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
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:
Send a report
If none of this helps, tokenade report sends redacted Tokenade logs and agent transcripts for analysis, after you type a consent phrase. Run tokenade report --dry-run first to build the archive locally (~/.tokenade/last-report.zip) and check what it contains without uploading. Use --message "…" to describe the problem. Details in What Tokenade sends and stores.
For background on how Claude Code hooks behave, see Claude Code hooks.