Docs / Commands
Maintenance commands
Updated
These commands keep a Tokenade install healthy: check it is wired correctly, see what the hooks are doing, spot tools that conflict with it, reclaim disk space and clean up a leaked secret. None of them sends anything over the network except upgrade.
Diagnose
healthcheck
Aliases: health, doctor. Runs one check per row and names the fix when something is wrong.
| Check id | What it verifies |
|---|---|
binary | Which tokenade binary runs and its version; warns when several copies are on your PATH |
gain_ledger | ~/.tokenade/gain.jsonl is writable |
agent_detect | Which agent is configured for this directory |
hook_installed | Tokenade's hook entries are present in ~/.claude/settings.json |
mcp_entry | No stale tokenade entry is left in an agent's mcpServers (Tokenade is hook-first) |
wrapped_mcps | Wrapped third-party MCP entries point at the current binary |
semantic_model | The embedding model is cached |
stale_mcp_procs | No old Tokenade MCP processes are running against a removed binary |
It also reports disk usage, license status, plugin bridges that never fired, Codex hook trust and, since 1.2.1, Claude Code folders whose trust prompt was not accepted (Claude Code runs no hooks there).
─── tokenade healthcheck ───
OK gain ledger writable at ~/.tokenade/gain.jsonl
OK every hook runs the same tokenade binary
OK Codex hooks trusted — compaction active (6 hook(s))
OK agent detected: claude-code
-- semantic model NOT cached (fetched once, ~30 MB, on first `semantic` use)
…
all checks passed
--json prints version, failures, ok and checks[], each with a stable id you can branch on in CI. Exit code 0 when every check passes (-- rows are informational), 1 when at least one row fails.
hooks
| Subcommand | Effect |
|---|---|
status (default) | Every installed Claude Code hook with its event, then recent hook activity |
tail [N] | The last N hook-fire records from ~/.tokenade/debug.log (default 20) |
detect
Prints which agent is running (from the environment, then from project files such as .claude/, .cursor/, AGENTS.md), the channel that agent type uses, and where it keeps its MCP config.
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 agent type, not your machine. To know whether Tokenade is actually installed, run tokenade health.
incompatibilities
Aliases: incompat, competitors, detect-competitors, scan. Looks for other token tools (config files, binaries, running daemons) and classes each one:
| Class | Meaning |
|---|---|
[redundant] | Tokenade already does this job; safe to remove |
[overlapping] | Tokenade supersedes it; migrate your data first, then remove |
[wasteful] | Known to inflate token usage; disabling is recommended |
[compatible] | Complementary; leave it installed |
Read-only. The fix-up itself runs during tokenade install (skip it with --no-cleanup).
discover and measure
tokenade measure [--json]
discover scans your Claude Code sessions from the last N days (default 30) and lists the 15 heaviest tools by bytes, whether the Bash hook is wired, and up to 5 tools the hooks would compress. measure sums the tokens of every file your agent loads at session start (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, .claude/*.md) against an 800-token target. Both are read-only.
audit-claude-md
Aliases: claudemd, audit-claudemd, claude-md-audit. Walks the CLAUDE.md cascade (the global file plus one per directory from the repo root down to DIR), reports the token cost of each file and the lines duplicated across files, with the tokens you would recover by keeping each in one place. Deterministic, no LLM.
read-mode
Shows how aggressively long listings and reads are folded. Set it with TOKENADE_READ_MODE:
| Mode | Keeps inline | Use for |
|---|---|---|
aggressive | Less | Cheap models, tight context |
task | Default | Default |
reference | More | Configs, schemas, full diffs |
entropy | The most informative lines, in order | Mixed output |
Aliases accepted by the variable: aggro/terse, ref/full, dense.
Clean up
evict-stale
Prunes everything Tokenade stores that hasn't been used for 7 days: caches, per-project code indexes, stashed outputs, session state and downscaled image copies. It also drops zero-saving rows from gain.jsonl, forgets projects that no longer exist, then compacts its local databases.
--models also deletes local model weights, which have no TTL and can be the largest thing Tokenade holds; they download again on demand. Without it, evict-stale only reports how much they take.
Safe to run any time. Once a stash entry is evicted, its hash can no longer be expanded and the command has to be re-run.
scrub-secret
Emergency tool when a credential leaked. Replaces every occurrence of <substring> with <redacted> in ~/.tokenade/debug.log, ~/.tokenade/gain.jsonl, ~/.tokenade/dedup.db and the stash; affected entries in semantic.db and file_search.db are dropped rather than patched.
Files are modified in place with no backup, since a backup would keep the secret. A real run shows what it found and asks before writing; --yes answers up front and is required when stdin is not a terminal. Scrubbing does not undo any earlier exposure: rotate the credential.
scrub-cache and redact
tokenade redact <file…> [--in-place] [--dry-run]
scrub-cache re-applies the built-in redaction patterns (AWS, GitHub, Stripe, Twilio, SendGrid and more) to every row of dedup.db and every text file in the stash. Run it after an upgrade or after rotating credentials. Idempotent.
[tokenade scrub-cache --dry-run] reporting what WOULD change; no writes
◐ dedup.db — 123 row(s) WOULD be redacted; …
◐ stash — 2 file(s) WOULD be redacted; …
-- file_search.db — nothing to redact
redact applies the same patterns to any file you choose. By default it writes <file>.redacted and leaves the original alone; --in-place overwrites atomically; --dry-run only counts. It streams line by line, so multi-GB files are fine.
Other utilities
| Command | Effect |
|---|---|
tokenade pack [PATH] [--budget N] [--diff | --base <ref>] [--out FILE] [--json] | Export a repo (or only changed files) as one markdown bundle under a token budget; files over budget are listed, not silently dropped |
tokenade turn-summary [--max N] [<file>|-] | Short summary of a conversation turn, in N sentences (default 5) |
tokenade add-compactor, tokenade trust-filters | Add your own compactors and approve a repo's filters; see custom compactors |
tokenade upgrade [--check | --on | --off] | Update in place from the signed release manifest; see upgrade and uninstall |