Docs / Agents
Claude Code (CLI and desktop)
Updated
Claude Code gets Tokenade's full coverage through hooks: every shell command, file read, search, web fetch and MCP result can be folded before it reaches the model. tokenade install sets it up when it finds Claude Code, including the copy built into Claude Desktop's Code tab. The one step that is yours: accept Claude Code's trust prompt in each folder you work in.
What install writes
All paths are under your home directory: ~ on Linux and macOS, %USERPROFILE% on Windows. If CLAUDE_CONFIG_DIR is set, Tokenade uses that directory instead of ~/.claude. With --per-project, it writes to ./.claude/ in the current folder.
| File | What Tokenade adds |
|---|---|
~/.claude/settings.json | Hook groups tagged _tag: "tokenade…", the statusLine savings ticker, and the auto-compact threshold (autoCompactWindow plus env.CLAUDE_CODE_AUTO_COMPACT_WINDOW) |
~/.claude/CLAUDE.md | A short Tokenade rules section, so the agent knows the tokenade commands |
.mcp.json, ~/.claude.json | Third-party MCP servers rewritten to start behind tokenade mcp-wrap (skip with --no-wrap-mcps) |
| Current folder | Project rules files (CLAUDE.md, AGENTS.md…) scaffolded on install |
Your own hooks, MCP servers and rules are kept. A statusLine you already set is wrapped, not replaced; tokenade statusline off opts out.
The hooks
| Event | Role |
|---|---|
| PreToolUse | Rewrites a shell command to tokenade wrap '<cmd>', redirects large reads and web calls to folded versions, snapshots a file before an edit |
| PostToolUse | Folds command output, file reads, search results and fetched pages; keeps the code index fresh after edits |
| SessionStart | Session context (for example recent dead ends) |
| UserPromptSubmit | Style note before each prompt |
| PreCompact | Runs before Claude Code compacts the conversation |
| SubagentStop | Subagent results |
Every hook is fail-open: if Tokenade crashes or is missing, the hook exits cleanly and your agent continues as if Tokenade were not there. How each hook works is described in How hooks intercept tool calls.
--no-hook skips the PostToolUse and Edit/Write index hooks. --autocompact-pct <N> changes the threshold (10-95, default 70); --no-autocompact removes the one Tokenade set.
Accept the folder trust prompt
Claude Code runs no hooks at all in an interactive session in a folder whose trust prompt you have not accepted. Tokenade's hooks are silently skipped there, and so is every other hook. Non-interactive runs (claude -p) are not affected.
When Claude Code asks whether you trust the folder, accept it. Since 1.2.1, tokenade healthcheck warns you, run from that folder:
accept the trust prompt when Claude Code opens this folder; `claude -p` runs are not affected
Tokenade never grants this trust for you. It also checks disableAllHooks in ~/.claude/settings.json: if it is true, no hook runs.
Claude Desktop
Code tab. It runs Claude Code itself and reads the same ~/.claude settings, so it gets the same hooks and the same coverage. Since 1.2.1, tokenade install sets it up even when no separate claude command is on your PATH, by checking the copy of Claude Code bundled with the app (under the app's data folder: ~/.config/Claude on Linux, ~/Library/Application Support/Claude on macOS, %APPDATA%\Claude on Windows, or the Microsoft Store build's own folder).
Chat. Chat runs no local commands or file reads, so only MCP optimisation applies. tokenade install wraps the servers in claude_desktop_config.json:
| OS | File |
|---|---|
| Linux | ~/.config/Claude/claude_desktop_config.json |
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Windows (Microsoft Store) | %LOCALAPPDATA%\Packages\Claude_…\LocalCache\Roaming\Claude\claude_desktop_config.json |
To wrap them again later: tokenade mcp-wrap install. Restart Claude Desktop after a change. See Wrap MCP servers.
Claude Cowork runs in an isolated environment that local tools cannot reach. It is not supported.
Verify
tokenade hooks tail # last 20 hook fires from ~/.tokenade/debug.log
tokenade healthcheck # hook_installed, wrapped_mcps, folder trust
Then use Claude Code for a few minutes and check tokenade gain. See your first session.
Turn it off or remove it
| Goal | Command |
|---|---|
| Disable hooks for one session or shell | Set TOKENADE_HOOK_DISABLED=1 in the environment Claude Code starts from |
| Run one command without compaction | tokenade raw <cmd> |
| Restore the original MCP entries only | tokenade unwrap-mcps |
| Remove the statusline ticker | tokenade statusline off |
| Remove everything | tokenade uninstall |
tokenade uninstall restores wrapped MCP servers first, strips the Tokenade block from ~/.claude/CLAUDE.md (after a backup), removes every _tag: "tokenade*" hook group from ~/.claude/settings.json, then deletes Tokenade's own data. Preview with tokenade uninstall --dry-run. See Upgrade and uninstall.