Environment variables
Updated
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
envblock 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 runtokenade 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 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 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.