Configuration
Every setting is an environment variable. The Read by column names the component that reads it:
- proxy: the LiteLLM context proxy (
proxy/smarter_compact/settings.py), which trims for Claude Code, Codex and OpenCode 1. - OpenCode 2: the in-process trim (
trimSettingsinplugin/lib/context-trim.mjs), configured by env or plugin options. - MCP: the
smart_compact_*tool server (plugin/lib/mcp/). - CLI:
smarter-compact, the agent hooks, and the proxy auto-start (plugin/lib/brand.mjs,plugin/lib/proxy-daemon.mjs).
A setting the proxy reads and OpenCode 2 does not has no effect on OpenCode 2 sessions.
Precedence
Section titled “Precedence”- Process environment.
~/.config/smarter-compact/proxy.env, for the keys listed there.~/.config/smarter-compact/config.toml, for trim thresholds,standing_instructionand[context_store].- Built-in default.
OpenCode plugin options override the environment (which reach what). Under Docker compose, the host shell or ./.env sets the variables compose.yaml lists, and proxy.env supplies the rest. The container does not read config.toml, so set those settings as variables.
| Variable | Default | Read by | Effect |
|---|---|---|---|
CONTEXT_PROXY_ENABLED |
1 |
proxy, OpenCode 2 | 0 forwards requests unchanged: no trim, compression, store or standing instruction |
CONTEXT_TRIM_AT_TOKENS |
unset | proxy, OpenCode 2 | Set: one threshold in estimated prompt tokens for every model. Unset: the model id picks a threshold from CONTEXT_TRIM_AT_OVERRIDES merged over built-in haiku 95000, else default 125000 |
CONTEXT_TRIM_AT_OVERRIDES |
unset | proxy, OpenCode 2 | JSON {"<family>": tokens, "default": tokens}; a family matches a substring of the lowercased model id. The CLI fills it from config.toml [context_proxy.trim_at]; set it by hand only where config.toml is not read (Docker) |
CONTEXT_TRIM_TO_TOKENS |
unset | proxy, OpenCode 2 | Older in-turn tool steps stay while the request is under this many estimated tokens, capped at the trim threshold. Set: one target for every model; a value that is not a positive integer counts as unset. Unset: built-in haiku 50000, else 66000 |
CONTEXT_TRIM_MIN_GAIN_TOKENS |
15000 |
proxy, OpenCode 2 | Skips a new trim that would free fewer estimated tokens than this, so the cache and the pointer note are not rewritten for a small gain; a forced trim (/compact) ignores it; 0 off |
CONTEXT_CLEAR_KEEP_RESULTS |
10 |
proxy, OpenCode 2 | N > 0: a trim first masks every tool result but the N newest, keeping turns and calls; it drops whole turns when masking leaves the prompt above the target; 0 off (research) |
CONTEXT_CLEAR_INPUTS_OVER_CHARS |
2000 |
proxy, OpenCode 2 | Where a trim clears, masks or evicts a tool result, each string over N characters in that call’s input becomes a placeholder naming its blob; 0 off (clearing) |
CONTEXT_STRIP_OLD_REASONING |
1 |
proxy, OpenCode 2 | A trim strips signed thinking from every assistant message but the latest (a message holding only thinking keeps it), estimates charge thinking signatures, and stripping alone can settle a trim; 0 restores the latest-run rule and uncharged signatures (reasoning) |
CONTEXT_MASK_OBSERVATIONS |
1 |
proxy, OpenCode 2 | Keeps tool calls in the kept region before the latest run and replaces their longer results with a placeholder; wins over CONTEXT_STRIP_PROSE; 0 off (research) |
CONTEXT_STRIP_PROSE |
0 |
proxy, OpenCode 2 | 1 strips tool calls and results from kept turns, keeping their text; under review (research) |
CONTEXT_PROGRESS_NOTE |
1 |
proxy, OpenCode 2 | Appends files edited and the last build/test commands to the trim pointer; 0 off (research) |
CONTEXT_SCRATCHPAD |
1 |
proxy, OpenCode 2, MCP server | Offers the smart_compact_scratchpad tool, nudges the agent once near the threshold to save task state, and shows the pad in every trim note (scratchpad); 0 turns it off, for the MCP server too (research) |
CONTEXT_SCRATCHPAD_NUDGE_AT |
0.75 |
proxy, OpenCode 2 | The nudge fires once the prompt passes this fraction of the trim threshold; 0 < x < 1, else the default |
CONTEXT_CHARS_PER_TOKEN |
2.5 |
proxy, OpenCode 2 | Token estimate ratio until the session reports usage (token estimate); must be > 0 |
CONTEXT_COMPRESS_OVER_TOKENS |
4000 |
proxy, OpenCode 2 | Tool results above this become a header plus smart_compact_get(id=...); 0 off |
CONTEXT_EVICTION |
0 |
proxy | 1 replaces the threshold trim with lifecycle eviction: every batch of assistant steps, rule-picked old tool results become their placeholder; Anthropic route only |
CONTEXT_EVICTION_BATCH |
3 |
proxy | Assistant steps per eviction batch; must be > 0 |
CONTEXT_EVICTION_KEEP |
12 |
proxy | Later tool results an unreferenced result needs before eviction takes it; must be > 0 |
CONTEXT_STANDING_INSTRUCTION |
1 |
proxy, OpenCode 2 | 0 omits the system note telling the agent to search before guessing |
CONTEXT_REUSE_RULES |
1 |
proxy, OpenCode 2 | The standing instruction ends with three static don’t-repeat-work rules (reuse context, rerun tests only after a change, revise scripts) after Hu et al., arXiv 2609.30725 §4.3; 0 restores the earlier bytes (text) |
CONTEXT_DEDUP_RESULTS |
1 |
proxy, OpenCode 2 | A new tool result of at least 200 characters identical to an earlier result still shown in full becomes a pointer naming its blob; only the newer copy changes; 0 restores the earlier bytes (clearing) |
CONTEXT_LEDGER |
0 |
proxy, OpenCode 2 | 1 turns it on: appends a ledger of files read (with ranges, current or stale) and modified to each new tool-result batch whose ledger changed, turns a covered read whose output is byte-identical to an earlier copy still shown in full into the repeated-result pointer (a changed output stays as it is), and nudges a covered read whose copy is gone and a test rerun with no edit since, after arXiv 2608.00808 §3.3–3.4 (clearing) |
CONTEXT_STRIP_REASONING_EVERY |
0 |
proxy, OpenCode 2 | N > 0: every N assistant steps, strip signed thinking from every assistant message but the latest between trims, when that frees at least CONTEXT_STRIP_REASONING_MIN_TOKENS; 0 off (reasoning) |
CONTEXT_STRIP_REASONING_MIN_TOKENS |
8000 |
proxy, OpenCode 2 | Estimated tokens a batched reasoning strip must free, else it waits for the next batch; 0 moves at every batch with reasoning to strip |
CONTEXT_LOG_REDUCE_OVER_CHARS |
6000 |
proxy, OpenCode 2 | N > 0: a new tool result over N characters that looks like test or build output keeps its failure-pattern lines with context and its last 40 lines, naming the full text’s blob, before head/tail compression; 0 turns it off (clearing) |
CONTEXT_KEEP_ERRORS |
3 |
proxy, OpenCode 2 | K > 0: each trim leaves the K newest error tool results of at most 2,000 characters (and their calls’ inputs) whole while clearing and masking the rest; 0 turns it off (clearing) |
CONTEXT_COLD_TRIM |
0 |
proxy, OpenCode 2 | 1: after an idle gap longer than the prompt cache lives, trim to the target below the threshold too (cache timing) |
CONTEXT_COLD_TRIM_SECONDS |
3600 |
proxy, OpenCode 2 | Cache lifetime a cold trim assumes when the request names none (non-Anthropic routes, the plugin) |
CONTEXT_COLD_TRIM_MIN_GAIN_TOKENS |
5000 |
proxy, OpenCode 2 | Estimated tokens a cold trim must free, else the request goes up untrimmed |
CONTEXT_CACHE_TTL_SPLIT |
0 |
proxy | N > 0, Anthropic route: message cache_control ttl "1h" goes up as "5m" while tools and system keep "1h", until the thread’s Nth idle gap over 5 minutes; 0 off (cache timing) |
Server-side tool-result clearing
Section titled “Server-side tool-result clearing”Anthropic route (/v1/messages) to Claude models only. Details: context proxy.
| Variable | Default | Read by | Effect |
|---|---|---|---|
CONTEXT_SERVER_CLEAR |
0 |
proxy | 1 appends a clear_tool_uses_20250919 context edit to each request |
CONTEXT_SERVER_CLEAR_TRIGGER_TOKENS |
100000 |
proxy | The edit’s trigger: clearing starts above this many input tokens; must be > 0 |
CONTEXT_SERVER_CLEAR_KEEP_TOOL_USES |
3 |
proxy | The edit’s keep: newest tool use/result pairs never cleared |
CONTEXT_SERVER_CLEAR_AT_LEAST_TOKENS |
5000 |
proxy | The edit’s clear_at_least, the cache-break gate; 0 omits it |
Proxy process
Section titled “Proxy process”| Variable | Default | Read by | Effect |
|---|---|---|---|
CONTEXT_PROXY_PORT |
4101 (Docker compose: 4100) |
CLI, proxy | LiteLLM listen port on 127.0.0.1; env wins over proxy.env; the proxy names its status file after it (proxy port) |
SMARTER_COMPACT_AUTO_PROXY |
1 |
CLI | 0, false or no stops hooks and plugins from starting the proxy |
SMARTER_COMPACT_PROXY_RUNTIME |
auto | CLI | docker or native; unset runs the proxy as a --restart always Docker container when the Docker daemon answers, else the uv-installed litellm (runtime) |
LITELLM_MASTER_KEY |
generated | LiteLLM | Key agents send in x-litellm-api-key. The CLI generates it into proxy.env (mode 600) and passes it to the proxy it starts |
SMARTER_COMPACT_ROOT |
package location | CLI | Package root holding proxy/smarter_compact_hook.py, when the proxy files moved |
CONTEXT_PROXY_ENV_FILE |
~/.config/smarter-compact/proxy.env |
Docker compose | env_file path for the container |
HOST_UID, HOST_GID |
required | Docker compose | User the container runs as, so the store stays host-owned |
Store and search
Section titled “Store and search”| Variable | Default | Read by | Effect |
|---|---|---|---|
SMARTER_COMPACT_STATE_DIR |
~/.local/share/smarter-compact |
all | Store parent; files live under context/ (location). OPENMEM_STATE_DIR is the pre-rename name, still read |
CONTEXT_STORE_TTL_DAYS |
30 |
proxy, MCP | Sessions idle longer are deleted at start, at most once a day; 0 keeps everything (retention) |
CONTEXT_EMBEDDING_MODEL |
empty (vectors off); enable writes smarter-compact-embed, the built-in model, to proxy.env |
proxy, OpenCode 2, MCP | Embedding model for hybrid search (vectors); an empty value in proxy.env opts out |
CONTEXT_EMBEDDING_URL |
http://127.0.0.1:11434/v1 (Docker compose: http://host.docker.internal:11434/v1) |
proxy, OpenCode 2, MCP | OpenAI-compatible base URL; requests go to POST <url>/embeddings |
CONTEXT_EMBEDDING_API_KEY |
empty | proxy, OpenCode 2, MCP | Bearer token, when the endpoint needs one |
CONTEXT_EMBEDDING_TIMEOUT_S |
30 |
proxy, OpenCode 2 | Seconds per row: a call of n rows times out after n × this |
CONTEXT_EMBEDDING_MAX_CHARS |
4000 |
proxy, OpenCode 2 | Characters of each row’s head that are embedded |
Install
Section titled “Install”| Variable | Default | Read by | Effect |
|---|---|---|---|
SMARTER_COMPACT_QUIET |
unset | CLI | 1, true or yes makes enable and disable print only errors and warnings, like -q |
SMARTER_COMPACT_INSTALL_CURSOR |
unset | CLI | 1 lets smarter-compact enable -g install the Cursor MCP and hooks when ~/.cursor exists |
Config files
Section titled “Config files”| File | Written by | Read by | Content |
|---|---|---|---|
~/.config/smarter-compact/proxy.env |
smarter-compact enable |
CLI, Docker compose (env_file) |
KEY=value lines. The CLI reads LITELLM_MASTER_KEY, CONTEXT_PROXY_PORT, and, when unset in the environment, every setting the proxy reads (PROXY_ENV_CONTEXT_KEYS in plugin/lib/brand.mjs) except SMARTER_COMPACT_STATE_DIR; the proxy the CLI starts gets them. CONTEXT_EMBEDDING_API_KEY goes to that proxy and to the embedding calls of the MCP server and the OpenCode 2 trim, never into an agent’s environment. Other keys are ignored |
~/.config/smarter-compact/config.toml |
smarter-compact context set |
CLI, hooks, OpenCode 2, MCP, the proxy the CLI starts | [context_proxy] trim_at_tokens (one threshold for every model) and [context_proxy.trim_at] (<family> = tokens, default = tokens), applied only when CONTEXT_TRIM_AT_TOKENS is unset. [context_proxy] standing_instruction (true/false) sets CONTEXT_STANDING_INSTRUCTION. [context_store] ttl_days (whole number >= 0), embedding_model, embedding_url, embedding_timeout_s, embedding_max_chars set CONTEXT_STORE_TTL_DAYS and the matching CONTEXT_EMBEDDING_*. Each applies only when its variable is unset in the environment and proxy.env; an invalid value is ignored and reported on stderr. Docker compose does not read this file |
Edit config.toml with the CLI, then restart the proxy or start a new session:
smarter-compact context listsmarter-compact context set haiku=95000 # per model familysmarter-compact context set trim=120000 # every modelsmarter-compact context unset haikuOpenCode plugin options
Section titled “OpenCode plugin options”OpenCode 2 maps each option to its variable for the in-process trim (src/options.mjs); a boolean option becomes 1 or 0.
| Option | Variable | Effect in OpenCode 2 |
|---|---|---|
enabled |
CONTEXT_PROXY_ENABLED |
yes |
standingInstruction |
CONTEXT_STANDING_INSTRUCTION |
yes |
trimAtTokens |
CONTEXT_TRIM_AT_TOKENS |
yes |
trimToTokens |
CONTEXT_TRIM_TO_TOKENS |
yes |
compressOverTokens |
CONTEXT_COMPRESS_OVER_TOKENS |
yes |
charsPerToken |
CONTEXT_CHARS_PER_TOKEN |
yes |
stateDir |
SMARTER_COMPACT_STATE_DIR |
yes: trim store, session registration, /compact flags and the registered MCP server |
proxyPort |
CONTEXT_PROXY_PORT |
proxy auto-start probes this port, over the environment and proxy.env, and starts a proxy there only when an agent config already points at it; the in-process trim does not use it |
OpenCode 1 applies only stateDir, to session registration and /compact flags. It trims in the proxy, which reads its own environment: set the trim variables or proxy.env, not plugin options.