# Maintenance commands

> Check your install, inspect hooks, find conflicting tools, reclaim disk space and scrub leaked secrets with Tokenade's maintenance commands.

Source: https://tokenade.net/en/docs/maintenance · Updated: 2026-10-07

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. Apart from `upgrade`, none of them contacts the network itself (like any `tokenade` call, they can start the daily background [update check](https://tokenade.net/en/docs/upgrade-uninstall), which `TOKENADE_NO_AUTO_UPDATE=1` turns off).

## Diagnose

### healthcheck

```text
tokenade healthcheck [--json]
```

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, 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).

```text
$ tokenade healthcheck
─── 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

```text
tokenade hooks <status|tail [N]> [--json]
```

| 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

```text
tokenade detect [--json]
```

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.

```text
$ 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 agent type, not your machine. To know whether Tokenade is actually installed, run `tokenade health`.

### incompatibilities

```text
tokenade incompatibilities [--json]
```

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

```text
tokenade discover [--days N] [--json]
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

```text
tokenade audit-claude-md [DIR] [--json]
```

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

```text
tokenade read-mode [--json]
```

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`, `balanced`/`default`, `ref`/`full`, `dense`.

## Clean up

### evict-stale

```text
tokenade evict-stale [--models]
```

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

```text
tokenade scrub-secret <substring> [--dry-run] [--yes]
```

Emergency tool when a credential leaked. Replaces every occurrence of `<substring>` with `<redacted>` in every `.jsonl` and `.log` file of `~/.tokenade/` (`debug.log`, `gain.jsonl`…), in `~/.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

```text
tokenade scrub-cache [--dry-run]
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.

```text
$ tokenade scrub-cache --dry-run
[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](https://tokenade.net/en/docs/custom-compactors) |
| `tokenade upgrade [--check \| --on \| --off]` | Update in place from the signed release manifest; see [upgrade and uninstall](https://tokenade.net/en/docs/upgrade-uninstall) |

## Related

- [Troubleshooting](https://tokenade.net/en/docs/troubleshooting)
- [Upgrade and uninstall](https://tokenade.net/en/docs/upgrade-uninstall)
- [Files and paths](https://tokenade.net/en/docs/files-and-paths)
- [What Tokenade sends and stores](https://tokenade.net/en/docs/privacy-telemetry)
