Docs / Configuration
Environment variables
Updated
TL;DR — Tokenade works with no configuration. The variables below turn individual features off (TOKENADE_HOOK_DISABLED=1, TOKENADE_NO_WEBSEARCH=1…) or tune thresholds and paths. Set them where the agent starts, not only in your shell.
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 1.2.2.
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_SESSION_COMPACT | Tokenade no longer trims transcripts whose prompt cache has expired at session start. | 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_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_STATUSLINE_PROMOS | 0, false, off or no hides the rotating ask in the ticker and keeps the figures. Same as tokenade statusline promos off. | promos shown |
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 and account
| 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 license and account files (license.key, machine-id, quota.json, the usage-report state, the update-check state). 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 |
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 |
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 downloads.tokenade.net (signed archive). | unset (Hugging Face first) |
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 a model Tokenade has no price for. They only change the dollar estimates in tokenade gain and the dashboard, never what is compacted. See How savings are measured.