Check it works: your first session

To check that Tokenade works, run tokenade healthcheck, then use your agent normally for a few minutes and look at tokenade hooks tail and tokenade gain. If hooks fire and the savings ledger grows, Tokenade is doing its job. You do not need to change how you prompt.

1. Run the health check

tokenade healthcheck

healthcheck (aliases health and doctor) verifies the install and prints one row per check. OK rows pass, -- rows are information, and a failing row names its fix. Trimmed example:

─── tokenade healthcheck ───

OK gain ledger writable at ~/.tokenade/gain.jsonl
OK all agent-config hook paths resolve
OK every hook runs the same tokenade binary
OK installed hook commands match the expected tokenade shape
OK Codex hooks trusted — compaction active (6 hook(s))
OK license active — plan: free · used … tokens saved (this month)
OK agent detected: claude-code

Exit code 0 means all checks pass (some may show info-only -- rows); 1 means at least one check failed. For scripts and CI, use tokenade healthcheck --json: each check carries a stable id (binary, gain_ledger, agent_detect, hook_installed, mcp_entry, wrapped_mcps, semantic_model, stale_mcp_procs).

The rows you most want to see:

license active: the machine is activated. If not, run tokenade login (details).
One row per wired agent, for example opencode plugin active — tool-result compaction firing or Codex hooks trusted.

Claude Code: accept the folder trust prompt

Claude Code runs no hooks at all, Tokenade's included, in an interactive session in a folder whose trust prompt you have not accepted. Since 1.2.1, healthcheck says so:

-- Claude Code has not trusted /path/to/project — in an interactive session here, it runs none of its hooks (tokenade's included)
accept the trust prompt when Claude Code opens this folder; `claude -p` runs are not affected

Open the folder in Claude Code and accept the prompt. See Claude Code.

2. See which agent Tokenade detects

tokenade detect

claude-code
coverage: hooks (PostToolUse) — command output is compacted and the saving is measured
mcp config hint: .mcp.json (third-party servers only)

The coverage: line describes the channel this type of agent uses, not whether it is installed on your machine. healthcheck answers that second question.

3. Use your agent

Start a session as usual and give the agent a task that produces output: run the test suite, a build, git log, read a large file, search the web. Nothing changes on your side. Long outputs reach the model folded, with a short banner that tells the agent how to get the full bytes back if it needs them (see Output compaction and the stash).

4. Watch the hooks fire

tokenade hooks status # installed Claude Code hooks
tokenade hooks tail # last 20 hook-fire records from ~/.tokenade/debug.log
tokenade hooks tail 50 # last 50

hooks status lists each installed hook with its event, then recent activity: how many times the hooks fired and when they last did.

If the activity list stays empty after you used the agent, the hooks are not running: see Troubleshooting.

5. Check your savings

tokenade gain

gain reads the local savings ledger (~/.tokenade/gain.jsonl) and prints the number of operations, tokens before and after, and a breakdown by operation. Useful variants:

tokenade gain --history # one row per ledger entry, after the summary
tokenade gain --by-source # split by source: cli / hook / mcp / proxy
tokenade dashboard # one-screen overview (alias: stats)

Everything gain and dashboard show is computed on your machine. How the figures are counted, and what is excluded, is explained in How savings are measured.

Still nothing?

Re-run tokenade install: it is idempotent and repairs missing hooks.
Make sure you did not run install with sudo (it writes to /root and refuses by default).
Check that TOKENADE_HOOK_DISABLED is not set in your agent's environment.
Check the agent-specific steps: Claude Code folder trust, Codex hook approval.