Docs / Configuration
Files and paths
Updated
Tokenade keeps everything it owns in two directories in your home: a state directory, ~/.tokenade/, and a cache directory, ~/.cache/tokenade/. Besides those, it writes its hooks and rules into your agents' own config files. Nothing is stored anywhere else unless you point it there with an environment variable.
The two trees, per OS
| Linux | macOS | Windows | |
|---|---|---|---|
| State | ~/.tokenade/ | ~/.tokenade/ | %USERPROFILE%\.tokenade\ |
| Cache | ~/.cache/tokenade/ | ~/.cache/tokenade/ | %LOCALAPPDATA%\tokenade\ |
How they are resolved:
- Home:
$HOMEon Linux and macOS. On Windows,%USERPROFILE%comes first, becauseHOMEis usually unset there (only Git Bash and MSYS2 set it). - Cache:
$XDG_CACHE_HOMEif set, else%LOCALAPPDATA%, else$HOME/.cache, else%USERPROFILE%\AppData\Local. An empty variable counts as unset. macOS uses~/.cache, not~/Library/Caches.
On Linux and macOS, Tokenade tightens these directories to owner-only permissions (0700 for directories, 0600 for sensitive files), because caches can hold command lines captured before redaction.
Inside ~/.tokenade/
Account and license (moved together by TOKENADE_CONFIG_DIR):
| File | What it is |
|---|---|
license.key | Signed license for this machine, written by tokenade login. |
machine-id | Stable identifier of this machine. |
quota.json | Last plan and quota status received from tokenade.net. |
reporter-offset, reporter-offset-estimated, report-health.json | How far the usage ledgers have been reported, and when tokenade.net was last reached. |
update-check.json, auto-update-off | Last update check; the marker written by tokenade upgrade --off. |
Savings and memory:
| File | What it is |
|---|---|
gain.jsonl | Measured savings ledger, one row per compaction. Rotates at 10 MiB. |
gain_estimated.jsonl | Estimated savings (brevity, batching), kept apart from measured ones. |
mistakes.jsonl | Dead-end memory. See Dead-end memory. |
redact.jsonl | Counts of which redaction rule fired and when. |
Indexes and caches (SQLite):
| File | What it is |
|---|---|
index.db | Symbol index for map, query, impact, keyed by project path. |
semantic.db | Embeddings for semantic and --prompt. |
dedup.db | Recently seen outputs, used to avoid sending the same bytes twice. |
fold_store.db, file_search.db | Folded-output store and file-search cache. |
Each of these five can be redirected with TOKENADE_DEDUP_DB, TOKENADE_INDEX_DB, TOKENADE_SEMANTIC_DB, TOKENADE_FOLD_STORE_DB and TOKENADE_FILE_SEARCH_DB.
Configuration and logs:
| File | What it is |
|---|---|
filters/ | Your own compactors, installed by tokenade add-compactor. See Custom compactors. |
trusted-filters.json | Content hashes of project filters you approved. |
install-options.json | The flags you passed to tokenade install, reused by later installs, upgrades and self-repair. tokenade install --defaults forgets them. |
statusline-off, statusline-promos-off | Markers written by tokenade statusline off and tokenade statusline promos off. |
shellproxy.sh, .csh, .nu, .cmd | Shell-proxy fragments sourced from your shell rc files. |
debug.log, debug.log.1 | Debug log, rotated at 16 MiB. Read it with tokenade hooks tail. |
dashboard.html | The local dashboard page written by tokenade dashboard. |
last-report.zip | The archive built by tokenade report (also by --dry-run). |
sessions/ | Small per-session state files, swept automatically. |
You will also see lock files, timestamps and one-shot markers. They are internal and safe to ignore.
Inside ~/.cache/tokenade/
| Path | What it is |
|---|---|
stash/ | Full outputs replaced by a summary, recoverable with tokenade expand-ref <hash>. Entries expire after 7 days; the directory is capped at 2 GiB (TOKENADE_STASH_MAX_DIR_BYTES). Move it with TOKENADE_STASH_DIR. |
stash-keep/ | Markers for stash entries that are the only copy of something. |
model/ | The local search model, about 132 MB, downloaded once on first semantic or --prompt use. Pre-seed it elsewhere with TOKENADE_MODEL_DIR. |
To see how much space all of this takes, run tokenade healthcheck: the disk-footprint row lists the biggest items.
Inside a project
A project directory can contain a .tokenade/ folder:
.tokenade/filters/*.toml: compactors shipped with the repository. They run only aftertokenade trust-filters..tokenade/reads/: PNG copies of images your agent cannot display (.tiff,.bmp,.ico…), converted so it can read them.
Tokenade adds .tokenade/ to your global git ignore file, ~/.config/git/ignore, so this folder is never committed by accident.
Agent config files Tokenade writes
tokenade install only edits what each detected agent needs. The main files:
| Agent | Files |
|---|---|
| Claude Code | ~/.claude/settings.json (hooks tagged tokenade, statusLine, env), ~/.claude/CLAUDE.md (a fenced <!-- tokenade:start --> block) |
| Codex | ~/.codex/hooks.json, hook trust entries in ~/.codex/config.toml, ~/.codex/AGENTS.md |
| Cursor | ~/.cursor/hooks.json, ~/.cursor/rules/tokenade.mdc |
| Antigravity | ~/.gemini/GEMINI.md |
| GitHub Copilot CLI | ~/.copilot/hooks/tokenade.json, ~/.copilot/copilot-instructions.md |
| OpenCode / Kilo Code | ~/.config/opencode/plugin/tokenade.ts, ~/.config/kilo/plugins/tokenade.ts |
If you moved Claude Code's config with CLAUDE_CONFIG_DIR, Tokenade follows it. With tokenade install --per-project, the agent files go into ./.<agent>/ in the current project instead of your home. The per-agent pages list every file; tokenade uninstall --dry-run prints the exact list on your machine.