# Environment variables

> Every user-facing TOKENADE_* environment variable: what it changes, its default, and where to set it so your agent's hooks see it.

Source: https://tokenade.net/en/docs/environment-variables · Updated: 2026-11-19

Tokenade needs no environment variable to work. The variables on this page let you switch a single feature off, move a data directory, or tune how much output gets folded. This page lists the ones meant for users, with their default and effect, as of 2.0.1.

## Where to set them

Most of Tokenade runs inside your agent's hooks, as child processes of the agent. A variable exported in your interactive shell only reaches those hooks if the agent was started from that shell. To make a setting stick:

- **Claude Code**: add it to the `env` block of `~/.claude/settings.json`.
- **Other agents**: set it in the environment the agent is launched from (shell profile, desktop launcher, service file).
- **Install-time variables** (`TOKENADE_ALLOW_ROOT`, `TOKENADE_NO_HOOK`, `TOKENADE_NO_STATUSLINE`, `TOKENADE_AUTOCOMPACT_PCT`): set them in the shell where you run `tokenade install`.

Boolean switches accept `1`, `true`, `yes` or `on` unless noted otherwise. `TOKENADE_NO_*` switches that only test for presence are marked "any value".

## Turning things off

| Variable | Effect | Default |
|---|---|---|
| `TOKENADE_HOOK_DISABLED` | Every hook passes the agent's tool call through untouched. Also works as a one-command prefix: `TOKENADE_HOOK_DISABLED=1 git log`. Values `1` or `true`. | unset (hooks active) |
| `TOKENADE_NO_HOOK` | `tokenade install` and the self-repair (`ensure-hooks`) skip writing hooks. Use it to keep an install without hooks. Values `1` or `true`. | unset |
| `TOKENADE_NO_WEBSEARCH` | Tokenade leaves the agent's web search alone, `tokenade search` refuses to run, and the rules Tokenade writes for the agent stop mentioning it. Run `tokenade install` once with it set so the rules are rewritten. | unset |
| `TOKENADE_NO_WEBFETCH` | The agent's WebFetch is no longer intercepted or compacted. Independent of `TOKENADE_NO_WEBSEARCH`. | unset |
| `TOKENADE_NO_GREP` | Grep/Glob output is not compacted. | unset |
| `TOKENADE_NO_GLOB` | The Glob result hook prints nothing; listings go through as-is. | unset |
| `TOKENADE_NO_MCP_HOOK` | Results from third-party MCP tools are not compacted by the hook (any value). | unset |
| `TOKENADE_NO_CODE_STRIP` | Source files Tokenade reads for the agent keep their comments. | unset |
| `TOKENADE_FORCE_BYPASS` | `1` lets `tokenade raw` re-run a command it would otherwise refuse to re-run because its output is already stashed. | unset |
| `TOKENADE_NO_SESSION_COMPACT` | Tokenade no longer trims transcripts whose prompt cache has expired at session start. | unset |
| `TOKENADE_NO_PRECOMPACT_MASK` | `1`: right before Claude Code compacts a session, Tokenade no longer folds the large tool results the summary would read. | unset |
| `TOKENADE_MAX_CACHE_TTL_SECS` | The prompt-cache lifetime, in seconds, that Tokenade assumes before it trims an idle transcript (at session start, on resume and in `tokenade compact-sessions`). Trusted as given, plus 5 minutes of margin: a value below 3600 can trim a session whose 1-hour cache is still warm. Unset, Tokenade reads the lifetime from each transcript. | unset |
| `TOKENADE_NO_AUTO_UPDATE` | Skips the background update check (24 h cadence). `tokenade upgrade --off` makes it permanent with a marker file. | unset |
| `TOKENADE_NO_STAR_INVITE` | Hides the one-time line, after `tokenade install` or in `tokenade dashboard`, that invites you to star the GitHub repository. It is never shown outside a terminal or under CI anyway. | unset |
| `TOKENADE_NO_STATUSLINE` | The installer and the self-repair do not wire the live ticker into Claude Code's `statusLine` (any value). `TOKENADE_STATUSLINE=0` (also `false`, `off`, `no`) does the same. | unset |
| `TOKENADE_AUTOCOMPACT` | `0`, `false` or `off` stops `tokenade install` from setting the agent's auto-compaction threshold. | on |
| `TOKENADE_NO_COLOR` | No colour in the dashboard banners (any value). The standard `NO_COLOR` is honoured too. | colour on a TTY |

## Install

| Variable | Effect | Default |
|---|---|---|
| `TOKENADE_ALLOW_ROOT` | Lets `tokenade install` run under `sudo`. Without it the install refuses, because hooks written to `/root` are never seen by your own agent. | unset (refuses) |
| `TOKENADE_AUTOCOMPACT_PCT` | Context-window percentage at which the agent is asked to auto-compact. Accepted range 10–95; out-of-range values are ignored. The `--autocompact-pct` flag of `tokenade install` wins over it. | `70` |
| `TOKENADE_CONFIG_DIR` | Directory for the update-check state (`update-check.json`, `auto-update-off`). An empty value or a boolean typo such as `1` is ignored. | `~/.tokenade` |
| `TOKENADE_DEBUG_LOG` | Path of the JSON-lines debug log. `tokenade install` sets it to `~/.tokenade/debug.log` in the hook commands unless you pass `--no-debug-log`. The file rotates at 16 MiB, keeping the last 8 MiB, and the previous file becomes `debug.log.1`. | set by install |
| `TOKENADE_HTTP_TIMEOUT_MS` | Per-request timeout of the npm installer when it downloads the binary. | `30000` |
| `TOKENADE_UPDATE_ENDPOINT` | Base URL the update check and `tokenade upgrade` fetch the signed manifest and binaries from, for a mirror. | latest GitHub Release |

## How much gets folded

| Variable | Effect | Default |
|---|---|---|
| `TOKENADE_READ_MODE` | How much of long listings and reads stays inline: `aggressive` (less), `task` (default), `reference` (more), `entropy` (keeps the most informative lines in order). Check the active value with `tokenade read-mode`. | `task` |
| `TOKENADE_DISCLOSE_THRESHOLD` | Token size above which incidental output (commands, fetched pages) is stashed and replaced by a summary. | `5000` |
| `TOKENADE_READ_DISCLOSE_THRESHOLD` | Same, for files the agent reads on purpose. | `25000` |
| `TOKENADE_RAW_BUDGET` | Token ceiling of one `tokenade expand-ref --raw` answer before it asks you to resume. `--budget 0` on the command still returns everything. | `60000` |
| `TOKENADE_IMAGE_MAX_EDGE` | Long edge, in pixels, images are downscaled to before the agent reads them. `0` disables downscaling; values from 1 to 63 are ignored. | `1024` |
| `TOKENADE_CACHE_HINTS` | Opt-in: prefixes compactor output with a prompt-cache marker, dropped whenever it would make the output larger than the raw input. | off |
| `TOKENADE_MCP_LEAN_SCHEMA` | Opt-in, value `1`: [`mcp-wrap`](https://tokenade.net/en/docs/mcp-wrap) also strips the `description` fields from MCP tool input schemas. | off |

## Storage locations

| Variable | Effect | Default |
|---|---|---|
| `TOKENADE_STASH_DIR` | Where full outputs are stashed for `expand-ref`. | `~/.cache/tokenade/stash` (see [Files and paths](https://tokenade.net/en/docs/files-and-paths) for Windows) |
| `TOKENADE_STASH_MAX_DIR_BYTES` | Size cap of the stash; the oldest entries are evicted beyond it. Entries also expire after 7 days. | `2147483648` (2 GiB) |
| `TOKENADE_MODEL_DIR` | A directory that already holds the embedding model for `semantic` and `--prompt`. If set and the files are missing, Tokenade errors instead of downloading. | unset (download to the cache) |
| `TOKENADE_MODEL_NO_HF` | Skip Hugging Face and fetch the model only from the project's GitHub Releases (signed archive). | unset (Hugging Face first) |
| `TOKENADE_MODEL_HF_BASE` | Host the model is downloaded from instead of Hugging Face (a mirror). Files are still checked against the digests built into the binary. | `https://huggingface.co` |

## Documents, media and execute

| Variable | Effect | Default |
|---|---|---|
| `TOKENADE_OCR_LANG` | Tesseract language pack(s) for OCR, e.g. `eng+fra`. | `eng` |
| `TOKENADE_WHISPER_MODEL` | Whisper model used for audio/video transcripts (`tiny`, `base`, `small`, `medium`…). | `base` |
| `TOKENADE_WHISPER_TIMEOUT_SECS` | Wall-clock limit for one transcription. | `900` |
| `TOKENADE_MAX_INPUT_BYTES` | Read limit for inputs that are not regular files (pipes, devices). | `1073741824` (1 GiB) |
| `TOKENADE_EXEC_SANDBOX` | `1` runs every `tokenade execute` script under bubblewrap (read-only filesystem, writable `/tmp`), like `--sandbox`. Refuses to run if `bwrap` is missing. | off |
| `TOKENADE_EXEC_SANDBOX_NET` | `1` keeps network access inside that sandbox, like `--sandbox-net`. | off |

## Redaction

Tokenade masks secrets in everything it hands back to the agent. These switches adjust the optional passes:

| Variable | Effect | Default |
|---|---|---|
| `TOKENADE_REDACT_PII` | Also masks e-mail addresses, phone numbers, IP and MAC addresses. Off by default because they appear constantly in ordinary output (`git log`, `docker inspect`). | off |
| `TOKENADE_NO_REDACT_PAN` | Turns off card-number/CVV masking. | on |
| `TOKENADE_NO_REDACT_ENTROPY` | Turns off the high-entropy string pass that catches unknown token formats. | on |

For these three, any non-empty value other than `0` counts as set.

## Dollar figures

`TOKENADE_PRICE_INPUT_PER_MTOK`, `TOKENADE_PRICE_CACHE_PER_MTOK` and `TOKENADE_PRICE_OUTPUT_PER_MTOK` set the price per million tokens used for rows with no known model and for the dollar value of estimated savings (defaults $3, $0.30 and $15). They only change the dollar estimates in `tokenade gain` and the dashboard, never what is compacted. See [How savings are measured](https://tokenade.net/en/docs/savings-measurement).

## Related

- [Files and paths](https://tokenade.net/en/docs/files-and-paths)
- [Custom compactors and filters](https://tokenade.net/en/docs/custom-compactors)
- [How hooks intercept tool calls](https://tokenade.net/en/docs/hooks)
- [Troubleshooting](https://tokenade.net/en/docs/troubleshooting)
