Skip to content

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 (trimSettings in plugin/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.

  1. Process environment.
  2. ~/.config/smarter-compact/proxy.env, for the keys listed there.
  3. ~/.config/smarter-compact/config.toml, for trim thresholds, standing_instruction and [context_store].
  4. 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)

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
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
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
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
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:

Terminal window
smarter-compact context list
smarter-compact context set haiku=95000 # per model family
smarter-compact context set trim=120000 # every model
smarter-compact context unset haiku

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.