# Files and paths

> Where Tokenade keeps its savings ledgers, caches, stash and model on Linux, macOS and Windows, and which agent config files it writes.

Source: https://tokenade.net/en/docs/files-and-paths · Updated: 2026-10-16

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](https://tokenade.net/en/docs/environment-variables).

## 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**: `$HOME` on Linux and macOS. On Windows, `%USERPROFILE%` comes first, because `HOME` is usually unset there (only Git Bash and MSYS2 set it).
- **Cache**: `$XDG_CACHE_HOME` if 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/`

Updates:

| File | What it is |
|---|---|
| `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, keeping the last 30 days. |
| `gain_estimated.jsonl` | Estimated savings (code intelligence, re-reads avoided, batching), kept apart from measured ones. |
| `gain.rollup.jsonl`, `gain_estimated.rollup.jsonl` | One row per day and compactor, never rotated: what keeps lifetime totals after rotation. |
| `mistakes.jsonl` | Dead-end memory. See [Dead-end memory](https://tokenade.net/en/docs/mistakes). |
| `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](https://tokenade.net/en/docs/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` | Marker written by `tokenade statusline 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`. |
| `sessions/` | Small per-session state files, swept automatically. |
| `style.json` | The response style set with [`tokenade style`](https://tokenade.net/en/docs/style-statusline). |
| `receipt-ed25519.key` | The per-install key that signs [`tokenade receipt`](https://tokenade.net/en/docs/gain-dashboard-receipt). |
| `litellm-costs.json`, `llm-costs.json` | Cached model price lists (LiteLLM, Helicone), refreshed at most once a day, used for dollar figures. |

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 after `tokenade 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.

## Related

- [Environment variables](https://tokenade.net/en/docs/environment-variables)
- [What Tokenade sends and stores](https://tokenade.net/en/docs/privacy-telemetry)
- [Upgrade and uninstall](https://tokenade.net/en/docs/upgrade-uninstall)
- [Output compaction and the stash](https://tokenade.net/en/docs/compaction)
