Configuration, without guesswork.

Default per-agent token budget. 0 = unlimited

Default 0

Allow automatic project-root re-rooting when absolute paths outside the jail are seen

Default false

Allow jailed ctx_* tools to read home-level IDE config dirs (registry-derived; covers all editors). Off by default — exposes other agents' sessions/credentials

Default null

Additional paths allowed by PathJail (absolute)

Default []

Trusted roots OUTSIDE $HOME lean-ctx may follow when an agent config is symlinked there (#596). Empty = strict $HOME-only

Default []

Automatic knowledge capture from tool findings

Default true

Opt-in: let adaptive learning signals (predictor, bandit, heatmap, adaptive policy, bounce/path memory) influence `auto` mode. Off by default for a deterministic, I/O-light cascade (capability guards + size/task heuristic only) that keeps output byte-stable for prompt caching. Override via LEAN_CTX_AUTO_MODE_LEARNING

Default false

In-band behavior hints (heavy full/raw reads, search→read→search chains): auto (default, one hint per pattern per session) or off. Detections are always counted for `tools health`.

Default "auto"

Maximum BM25 cache file size in MB

Default 128

Enable the experimental local buddy helper. It does not enable a public multi-agent product or MCP surface.

Default true

Bypass-hint mode: when agents use native Read/Grep instead of lean-ctx tools, a hint is appended to the next tool response. on (default), off, aggressive (hint on every call, no cooldown). Override via LEAN_CTX_BYPASS_HINTS

Default "on"

Token budget for the in-memory ctx_read cache (0 = built-in default 500k). When exceeded, least-valuable entries are evicted immediately via RRF (recency x frequency x size) so reads never block; eviction is not deferred to the staleness TTL

Default 0

Cache policy for ctx_read: aggressive (13-tok stubs), safe (map on hit), off (always disk)

Default "aggressive"

Session checkpoint interval in minutes

Default 15

Global compression intensity 0.0 (lossless) – 1.0 (max), mapped onto read modes/entropy/IB. Empty = per-mode defaults

Default null

Unified output-style level for the model's prose (not tool-output compression). lite=plain concise (default), standard/max=denser symbolic 'power modes'

Default "lite"

Named configuration overlay to merge from [profiles.<name>]

Default ""

Enable Rabin-Karp chunking for cache-optimal output ordering

Default false

Opt-in: losslessly crush array-heavy JSON from verbatim data commands (gh api, jq, kubectl get -o json, curl). Off by default keeps them verbatim. Reshapes only when it at least halves the payload; fully reconstructible

Default false

Custom command aliases (array of {command, alias} entries)

Default []

Require Bearer-token auth for the dashboard (default true). Set false for no-auth mode protected by Sec-Fetch-Site/Origin/Host checks. Override per-run with --no-auth or LEAN_CTX_DASHBOARD_AUTH

Default true

Opt-in (default off): write a human-readable debug log of intercepted MCP tool calls and hook routing decisions (lean-ctx vs native, with the reason) to <state_dir>/logs/debug.log. View with `lean-ctx debug-log`

Default false

Tool categories active by default. `core` is the default; `session` enables experimental local collaboration tools only when explicitly listed. Override via LCTX_DEFAULT_CATEGORIES

Default []

Serve explicit full/lines re-reads of changed cached files as diffs (opt-in). Override via LCTX_DELTA_EXPLICIT=1

Default false

Tools to exclude from the MCP tool list

Default []

Append wakeup briefing (facts, session summary) to ctx_overview output. Set false to reduce context bloat when calling ctx_overview frequently.

Default true

Commands to exclude from shell hook interception

Default []

Extra glob patterns to ignore in graph/overview/preload

Default []

Extra project roots for multi-root workspaces (auto-added to PathJail allow-list)

Default []

Maximum files included in the graph index. 0 means unlimited. The captured default is 15000.

Default 15000

The captured schema's prose still calls 0 the default. This reference follows its structured default value.

Verbatim binary path/expression for generated agent-hook commands (e.g. $HOME/.local/bin/lean-ctx) — for settings files synced across machines with different usernames. Shell-expanded by the hook host at run time; doctor accepts it as current. Empty = automatic absolute-path resolution

Default null

Write human-readable activity journal to ~/.lean-ctx/journal.md

Default true

Simplified disk budget in MB (0 = disabled). Distributes: archive ~25%, BM25 ~10%

Default 0

Cap rayon threads for the CPU-heavy index build (0 = all cores). Bounds per-instance CPU so concurrent sessions don't saturate the host on startup

Default 0

Soft process-RSS target as % of system RAM (1-50, default 5); eviction/throttling policy, not an OS hard cap

Default 5

Auto-purge data older than N days (0 = disabled). Flows into archive.max_age_hours

Default 0

Controls how aggressively memory is freed when idle

Default "aggressive"

Controls RAM vs feature trade-off (performance = max quality)

Default "performance"

Skip session/knowledge/gotcha blocks in MCP instructions

Default true

Disable all automatic read-mode degradation. Override via LCTX_NO_DEGRADE=1

Default false

Controls how dense/compact MCP tool output is formatted

Default "normal"

URLs to pass through without proxy interception

Default []

Filesystem path jail. null/true = enforced (tools confined to the project root + allow_paths). false = the blanket "any path" opt-out — every tool path is allowed (for containers/sandboxes where the boundary is external). Compression and secret redaction are unaffected. Flip both planes at once with `lean-ctx yolo` / `lean-ctx secure`

Default null

Mirror the host IDE's permission rules onto lean-ctx tools (v1: OpenCode). When on, ctx_shell honors your bash/rm * rules instead of bypassing them

Default "on"

Active context persona (persona-spec-v1): selects the domain bundle — tool surface, read-mode/compressor/chunker defaults, intent taxonomy, sensitivity floor. Built-ins: coding (default), research, lead-gen, support, data-analysis; or a custom <name>.toml from the personas dir. Override via LEAN_CTX_PERSONA

Default "coding"

Disable lean-ctx edit tools (ctx_edit, ctx_patch) so the host's native editor handles edits (#454)

Default false

Already-compact output formats preserved verbatim instead of recompressed (e.g. ["toon"]). Set to [] to disable

Default ["toon"]

Persistent profile name. Checked after LEAN_CTX_PROFILE env var. Set via: lean-ctx config set profile passthrough

Default ""

Named partial configuration overlays; nested tables merge recursively over base settings

Default {}

Explicit project root directory. Prevents accidental home-directory scans

Default null

Per-turn tool-precedence reinjection (#1288): the UserPromptSubmit hook emits a one-line additionalContext reminder that ctx_* tools are the mandated path, so it always post-dates session-level harness instructions preferring native Bash. auto (default): active only while shadow_mode is on. Costs ~45 tokens per turn when active

Default "auto"

Enable/disable the proxy layer. null = auto-detect, true = force on, false = force off

Default null

Skip ALL proxy authentication on loopback binds. MCP/HTTP clients work without tokens. Ignored on non-loopback (gateway mode)

Default false

Custom proxy port (default: 4444). Useful for multi-user systems. Env: LEAN_CTX_PROXY_PORT

Default null

Require lean-ctx Bearer token authentication and disable provider API key fallback

Default false

Proxy reachability timeout in ms (default: 200). Override via LEAN_CTX_PROXY_TIMEOUT_MS

Default null

Controls the PostToolUse native-Read re-read dedup. auto (default): replace only re-reads of unchanged files with the compact stub, and only on guard hosts (Claude Code / CodeBuddy) where the PreToolUse redirect is off — first reads stay byte-identical and the read-before-write guard is untouched. on: dedup wherever the hook fires. off: never replace a Read result

Default "auto"

Read-only sibling roots: reads allowed, writes always denied (edit/refactor/export)

Default []

Controls the native-Read → ctx_read redirect hook. auto (default): redirect everywhere except hosts with a native read-before-write guard (Claude Code / CodeBuddy), where rewriting Read to a temp copy breaks native Write/Edit (#637). on: always redirect. off: never redirect native Read (ctx_read MCP tool + Grep/Glob redirect stay active)

Default "auto"

Verbosity of the reactive recovery footer on compressed output (path-first, MCP-optional)

Default "minimal"

URL patterns to exclude from proxy redirection

Default []

Store large tool outputs as references instead of inline content

Default false

Controls how verbose tool responses are

Default "normal"

How rules load for CLAUDE.md/AGENTS.md/GEMINI.md agents: shared block, dedicated (no shared-file edits; SessionStart hook / instructions[] / context.fileName), or off (write no rules file — for hosts that supply their own steering or phase-isolated/non-caching harnesses). Override via LEAN_CTX_RULES_INJECTION

Default "shared"

Where agent rule files are installed. Override via LEAN_CTX_RULES_SCOPE

Default "both"

Sandbox strictness level (0=default, 1=strict, 2=paranoid)

Default 0

Controls visibility of token savings footers: always (default, show on every response), never, auto (context-dependent). Also: LEAN_CTX_SHOW_SAVINGS=1|0

Default "always"

Retention window for explicit session cleanup; independent from archive retention and preserves the newest session per project

Default 7

Default on: denies native tools at the permission level, forcing agents to use ctx_* MCP tools for maximum compression. Disable with shadow_mode = false if you prefer native tools.

Default true

Controls when the shell hook auto-activates aliases (agents-only since #699: transparent in plain human terminals)

Default "agents-only"

Allow ctx_shell file-write redirects (>, >>, tee, heredoc-to-file, curl -o, wget default mode). Default false — prefer the native Write/Edit tool. The real command gating (allowlist, dangerous-pattern, interpreter-eval) still applies

Default false

Optional shell command allowlist. When non-empty, only listed binaries are permitted

Default []

Commands merged on top of shell_allowlist without replacing the defaults. Managed via `lean-ctx allow <cmd>`

Default []

Shell command timeout (seconds) for heavy commands (cargo build/test, make, docker build, git commit/push). null = built-in 10-minute ceiling

Default null

Disable shell hook injection

Default false

How the PreToolUse shell hook treats native Bash/Shell calls (#1278). rewrite: rewrite known read/search/list commands, unknown commands pass through raw. deny: block native shell outright so every command goes through ctx_shell (fail-opens: lean-ctx disabled, MCP daemon dead, explicit shadow-only surface). auto (default): currently rewrite

Default "auto"

Shell command gating: enforce (default, secure), warn (log only, never block) or off (skip allowlist + hard blocks; compression stays active)

Default "enforce"

Block $(), backticks, <() in shell arguments. Default false = warn only.

Default false

Shell command timeout (seconds) for normal commands. null = built-in 2-minute default. LEAN_CTX_SHELL_TIMEOUT_MS overrides both tiers (in ms)

Default null

Do not install agent CLI aliases (claude, codex, gemini) into shell rc files. Existing alias blocks are removed on next setup

Default false

Commands taking longer than this (ms) are recorded in the slow log. Set to 0 to disable

Default 5000

Opt-in: bias `auto` toward structure-first reads (map) for medium code files on a cold read. Off by default — for phase-isolated harnesses with no warm-session cache payback. Override via LEAN_CTX_STRUCTURE_FIRST

Default false

Opt-in: α-code identifier substitution in aggressive reads (>50-file projects). Off by default — abbreviated symbols hinder editing/refactoring

Default false

Research-only organization roll-up switch. Off by default and inactive in the public local Runtime.

Default false

Research-only organization roll-up credential. Inactive in the public local Runtime.

Default null

Research-only organization roll-up URL. Inactive in the public local Runtime.

Default null

Controls when shell output is tee'd to disk for later retrieval

Default "highcompression"

Controls agent output verbosity via instructions injection

Default "off"

Dashboard color theme

Default "default"

Tool visibility profile: minimal (5 tools), standard (16), power (all). Override via LEAN_CTX_TOOL_PROFILE

Default ""

Explicit list of enabled tool names. Used only when no tool_profile is pinned (tool_profile takes precedence); leave tool_profile unset to apply this list. The universal invoker ctx_call stays advertised so unlisted tools remain reachable — add it to disabled_tools (disabled_tools = ["ctx_call"]) to make this allowlist authoritative.

Default []

Legacy flag for maximum compression (use compression_level instead)

Default false

Disable the daily version check

Default false

Absolute paths allowed for ctx_shell redirects and tee output; empty = OS temp directories

Default []

Enable zero-loss compression archive

Default true

Replace large results with summary+ref (ctx_expand to retrieve). Env: LEAN_CTX_EPHEMERAL

Default true

Minimum output tokens before the ephemeral firewall replaces inline body with summary+ref. Env: LEAN_CTX_EPHEMERAL_MIN_TOKENS

Default 2000

Maximum ctx_shell(inline=true) output size in bytes before archive/firewall handling. Env: LEAN_CTX_INLINE_MAX_BYTES

Default 32768

Maximum age of archived entries before cleanup

Default 48

Maximum total disk usage for the archive

Default 500

Programs whose ctx_shell output is a dataset (rows/JSON) and passes through verbatim at any size, never archived or elided. `gh` is included automatically when the command uses --json/--jq. Set to [] to disable

Default ["sqlite3","psql","duckdb","jq"]

Minimum output size (chars) to trigger archiving

Default 800

Context-window cap for implicitly verbatim ctx_shell deliveries (dataset passthrough, inline=true): above this many tokens the delivery becomes a lossless head+tail digest + ctx_expand ref. Explicit raw/bypass is never capped; 0 disables. Env: LEAN_CTX_VERBATIM_MAX_TOKENS

Default 100000

Auto-consolidate knowledge periodically

Default true

Auto-deduplicate repeated reads

Default true

Auto-preload related files on first read

Default true

Auto-load graph-related files

Default true

Enable the background cognition loop (periodic knowledge consolidation)

Default true

Seconds between cognition loop iterations

Default 3600

Maximum steps per cognition loop iteration (>= 9 enables observation synthesis)

Default 9

Minimum facts per entity before observation synthesis writes a summary (needs cognition_loop_max_steps >= 9)

Default 3

Minimum seconds between consolidation runs

Default 120

Consolidate knowledge every N tool calls

Default 25

Number of repeated reads before dedup triggers

Default 8

Enable autonomous background behaviors

Default true

Suppress preload notifications in output

Default true

Log audit events when cross-project access occurs

Default true

Allow importing knowledge from other projects

Default false

Allow searching across project boundaries

Default false

Load universal (cross-project) gotchas

Default true

Research-only hosted synchronization setting. Inactive in the public local Runtime; use only with an explicit development evaluation flag.

Default false

Fixed per-session context budget (tool schemas + MCP instructions + auto-loaded rules + wakeup briefing). `doctor overhead` warns past this; `doctor overhead --gate` exits non-zero for CI. 0 disables the warning

Default 8000

Inject relevant CCR archives into later tool responses

Default true

Maximum proactive archive tokens per tool response

Default 2000

Maximum age of CCR content eligible for proactive expansion

Default 3600

Minimum normalized BM25 score for proactive expansion

Default 0.6

Fallback pricing model for MCP-only IDEs whose real model lean-ctx cannot observe (Cursor, Copilot, Windsurf, …). Unset → blended heuristic. Per-IDE overrides live in [cost.models]

Default null

Operator price overrides per model, USD per million tokens: [cost.prices."<model>"] with input_per_m / output_per_m / cache_write_per_m / cache_read_per_m. For negotiated enterprise rates (committed-use discounts, Azure PTU, zero-rated internal models); overrides embedded and live catalog rows, only a provider-measured bill beats it

Default []

Auto-extract decisions from completed sessions

Default true

Share knowledge facts across agent sessions

Default true

On-device embedding model for semantic retrieval

Default "minilm-l6"

Maximum knowledge facts extracted per session

Default 50

Enable embedding-based knowledge retrieval (requires model download)

Default false

The alias definition to execute

Default ""

The command pattern to match (e.g. 'deploy')

Default ""

Enable the MCP decision-loop runtime

Default true

Maximum lossy post-dispatch triage level (0 disables output filtering)

Default 0

Download the embedding model in the background on first semantic need (default: allowed). Set false for air-gapped machines; semantic features then stay off until a model is provided manually.

Default null

Pin embedding inference to a single CPU thread with no GPU provider so vectors are bit-identical across machines (default: off, multi-threaded GPU-capable path). Extractive prose ranking is already deterministic via score quantization; enable this only for cross-machine reproducibility, at a throughput cost.

Default null

Declared embedding width for hf: custom models (fallback only — the real width is probed from the ONNX graph at load time). Built-in models ignore this key.

Default null

Local ONNX embedding model for ctx_semantic_search. One of: minilm (all-MiniLM-L6-v2, 384d, default), nomic (768d) — or any HuggingFace repo with an ONNX export via hf:org/repo[@revision] (e.g. hf:jinaai/jina-embeddings-v2-base-code for code). Switching models re-indexes once on the next search.

Default "minilm"

Research-only hosted publication setting. Off by default and inactive unless LEAN_CTX_EXPERIMENTAL_PUBLICATION=1 is set for a local development evaluation.

Default false

Minimum hours between development-evaluation publishes (throttle; default 24)

Default 24

Optional development-evaluation display name for a hosted publication experiment

Default null

Timestamp of the last development-evaluation publish (written for throttling — not meant to be edited)

Default null

Research-only public-ranking setting. Off by default and inactive in the public local Runtime.

Default false

Aggregated-catalog cache lifetime in seconds

Default 300

Per-operation timeout for downstream connect/list/call (seconds)

Default 30

Enable the MCP Tool-Catalog Gateway (no-op when false)

Default false

How many tools `ctx_tools find` returns per query (clamped 1..=50)

Default 5

Env var holding the upstream credential the gateway injects as `Authorization: Bearer <env value>` (callers never see it)

Default ""

Research-only per-server switch (default true once a development configuration explicitly adds this server)

Default true

Registry id; becomes the governed route `/mcp/{id}` on the proxy port (lowercase alnum/-/_)

Default ""

Upstream Streamable-HTTP endpoint (HTTPS; loopback HTTP ok; plain HTTP needs [proxy] allow_insecure_http_upstream)

Default ""

Arguments for the spawned command (stdio transport)

Default []

Executable to spawn (stdio transport)

Default ""

Per-server switch (default true)

Default true

Extra environment variables for the child process (stdio transport)

Default {}

Extra request headers, e.g. Authorization (http transport)

Default {}

Stable server id; becomes the catalog namespace (`name::tool`)

Default ""

Secret environment variables mapped to memento references (stdio transport)

Default {}

Secret HTTP headers mapped to memento references (http transport)

Default {}

Transport: stdio (spawn command) or http (connect to url)

Default "stdio"

Streamable-HTTP endpoint (http transport)

Default ""

Learn co-access edges from real sessions (files surfaced together), surface them as decaying `co_access` graph edges, and boost recall by them. Set false for a purely static AST-only graph.

Default true

Globs dropped from the index corpus (root-relative, forward slashes), e.g. ["**/*.csv", "fixtures/**"]. Wins over include. CLI --exclude appends per run. Excluded files produce no chunks, graph nodes, or embeddings.

Default []

When non-empty, ONLY matching files enter the index corpus, e.g. ["**/*.rs", "**/*.ts"]. Empty = no restriction. CLI --include replaces this set per run.

Default []

Honor .gitignore / global gitignore / .git/info/exclude during index walks. false indexes ignored files too (the vendor-directory guard still applies). CLI override: --no-gitignore / --respect-gitignore.

Default true

LLM backend provider

Default "ollama"

Override the backend's base URL (empty = the backend's own default)

Default ""

Enable optional LLM enhancements (query expansion, contradiction explanation)

Default false

Model name for the selected backend

Default "qwen2.5-coder:1.5b"

HTTP timeout for LLM requests

Default 10

Repetitions before blocking. 0 = disabled

Default 0

Repetitions before reducing output

Default 2

Repetitions before further reducing output

Default 4

Maximum unique searches within a loop window

Default 10

Per-tool total call limits within a session. Keys are tool names, values are max calls

Default {"ctx_read":100,"ctx_search":80,"ctx_semantic_search":60,"ctx_shell":50}

Time window in seconds for loop detection

Default 300

Custom path to gopls binary

Default null

Custom path to pylsp binary

Default null

Custom path to rust-analyzer binary

Default null

Custom path to typescript-language-server binary

Default null

Maximum number of embedding facts stored

Default 2000

Maximum actions tracked per episode

Default 50

Maximum number of episodes retained

Default 500

Maximum characters in episode summary

Default 200

Default decay rate for gotcha importance

Default 0.03

Maximum gotchas stored per project

Default 100

Maximum gotchas retrieved per room per query

Default 10

Confidence threshold for contradiction detection

Default 0.5

Maximum number of knowledge facts stored per project

Default 200

Maximum history entries retained

Default 100

Maximum number of patterns stored

Default 50

Maximum facts returned per recall query

Default 10

Maximum number of relations returned

Default 40

Maximum number of rooms returned

Default 25

Maximum number of timeline entries returned

Default 25

Scale Ebbinghaus stability by fact archetype so structural evidence decays slower than inference (default false)

Default false

Characteristic memory stability (days) for the Ebbinghaus curve

Default 90

Rate at which knowledge confidence decays over time

Default 0.01

Forgetting curve: ebbinghaus (default, exponential + spacing) or linear

Default "ebbinghaus"

Threshold below which facts are considered low-confidence

Default 0.3

Master switch for the proactive capacity reclaim (#995). false trims only the overflow (escape hatch, no headroom); eviction stays lossless either way

Default true

Proactive headroom on a capacity reclaim: settle a full store at 1 - this fraction (0.25 = 75%) instead of churning at the cap. Lossless — the reclaimed tail is archived and restorable

Default 0.25

Similarity threshold for deduplication

Default 0.85

Days after which unused facts are considered stale

Default 30

Maximum number of learned procedures stored

Default 100

Maximum window size for pattern analysis

Default 10

Minimum repetitions before a pattern is stored

Default 3

Minimum sequence length for procedure detection

Default 2

Glob patterns for path-like tool arguments; a hit exempts the call's output from every lossy filter (same standard as raw=true)

Default []

Honor inline <protect> spans: matching output bypasses lossy line filtering and history pruning

Default true

Capture MCP edit tool changes in provenance

Default true

Capture native editor changes in provenance

Default true

Create provenance checkpoints when commits are made

Default true

Enable edit provenance capture

Default true

Days to retain edit provenance records

Default 90

Auto-ingest provider results into BM25/embedding indexes

Default true

Default cache TTL for provider results (seconds)

Default 120

Master switch for the provider subsystem (GitHub, GitLab, etc.)

Default true

GitHub API base URL (for GitHub Enterprise)

Default null

Enable/disable GitHub provider

Default true

GitLab API base URL (for self-hosted instances)

Default null

Enable/disable GitLab provider

Default true

Arguments for the MCP server command

Default []

Environment variable name containing auth token for MCP server

Default null

Command to spawn a local MCP server (stdio transport)

Default null

HTTP/SSE URL for a remote MCP server

Default null

Allow a custom (non-allowlisted) HTTPS upstream host, e.g. a corporate gateway in front of the provider API. Opt-in; default false. Unlike the env var, this config flag reaches the managed (service-spawned) proxy started by `proxy enable`/`restart` (#590)

Default false

Allow a non-loopback plaintext http:// upstream (trusted local network only, e.g. http://host.docker.internal:2455 in front of codex-lb). Opt-in; default false

Default false

Custom upstream URL for Anthropic API proxy

Default null

Opt-in active cache-aligner relocate (#974). When on, the proxy rewrites an unanchored Anthropic system prompt into a stable block (volatile values - ISO dates/datetimes, UUIDs, git SHAs - replaced by constant placeholders) carrying the cache_control breakpoint, plus an uncached trailing block that re-states the relocated values. The cacheable prefix then stays byte-stable turn-to-turn and finally caches; only the small tail is reprocessed. Anthropic-only, Treatment-arm, gated on a client that anchored nothing and on Anthropic's minimum cacheable size. Deterministic (#498) and idempotent. The cache_aligner telemetry is the precursor that quantifies the saving. Default false

Default true

Cache-aligner volatile-field telemetry (#940), on by default. The proxy scans each unanchored Anthropic system prompt for volatile, cache-busting fields (ISO dates/datetimes, UUIDs, git SHAs) and reports how many it found on /status cache_safety (volatile_system_requests, volatile_fields_detected) - purely to quantify how much prompt-cache the client leaks. Measurement only: the request body is never mutated, so it is strictly cache-safe, which is why it ships on for every proxy (#986 premium defaults). The deterministic scan is the precursor to the opt-in tail-relocate below. Set false to opt out of the per-request scan. Default true

Default true

Opt-in active prompt-cache breakpoint injection for Anthropic (#939). When on and the client set no cache_control of its own, the proxy adds one cache_control: {type:ephemeral} marker to the system field so an otherwise-uncached, stable system prompt bills later turns at the cached rate (the win a raw API client leaves on the table). Anthropic-only: OpenAI/Gemini cache prefixes automatically and ignore the marker, so those paths stay byte-unchanged. Deterministic, never adds a second breakpoint, and skipped below Anthropic's minimum cacheable size. Default false

Default false

Cache-economics (#986), on by default. Enables prompt-cache miss attribution telemetry (per turn, classify the outcome as cold start / warm reuse / TTL lapse / prefix change and report cumulative gauges on /status cache_attribution) plus a net-cost gate on the cold-prefix repack that skips re-seeding prefixes too small to be cached (below Anthropic's ~1024-token minimum). The telemetry never mutates the body and the gate only makes repacking more conservative, so it can never bust a cache that would otherwise have been kept - both halves are strictly safe, so every proxy gets them out of the box (#986 premium defaults). Set false to opt out (drops the /status attribution gauges and the per-request prefix hash). Default true

Default true

Opt-in in-band CCR retrieval for a remote proxy with no shared filesystem (#493). When on, a lossy stub advertises a compact <lc_expand:HASH> marker instead of a local tee path; when the model echoes that marker, the proxy splices the verbatim original (from its local tee store) back inline next turn — one turn of latency, no MCP/filesystem on the agent host. The splice is a strict no-op on marker-less turns, so it never perturbs the provider cache prefix unless the model asked to expand. Default false

Default false

Custom upstream URL for ChatGPT/Codex subscription API proxy

Default null

Opt-in routing of a Codex ChatGPT-subscription login through the proxy for model-turn compression (#603/#616). Default false leaves Codex native (history visible, cloud/remote intact, no #597). When true, setup pins model_provider = leanctx-chatgpt + chatgpt_base_url + a [model_providers.leanctx-chatgpt] block, so model turns route through /backend-api/codex/responses (the proxy strips the responses-lite marker so every model incl. gpt-5.5 works); pinning a provider scopes Codex history to it (#597), hence opt-in. Toggle durably with `lean-ctx proxy codex-chatgpt on|off|status`. Default false

Default false

Opt-in big-gap cold-prefix repack (#480): on a session-resume request the proxy may predict (from idle time vs the provider cache TTL) that the client-cached prefix has already expired, then prune that now-cold prefix to re-seed a leaner cache and keep applying the same deterministic compression on later turns so warm follow-ups hit it (sticky; baselines persist across restarts, #499). A wrong guess re-bills cache reads as writes (~12x), so default false

Default true

File-path globs whose reads are never compressed (#1150): a matching path is returned verbatim (full) by the read tools, for files where exact bytes matter more than token savings (golden snapshots, byte-asserted fixtures, security-sensitive configs). Globs (*/**/?) match the path and its file name, so *.snap, **/golden/**, tests/fixtures/* all work. Empty (default) protects nothing — the lossless crushers and beneficial gate already keep compression safe; this is an explicit escape hatch

Default []

Extra response header carrying the upstream gateway's billed USD for the turn (e.g. a corporate gateway's cost header). LiteLLM's x-litellm-response-cost is always recognized. Measured header costs beat table estimates; body-reported costs (OpenRouter usage.cost) beat headers

Default null

Opt-in counterfactual savings metering (#701): each rewritten Anthropic /v1/messages request fires a free count_tokens probe with the original, uncompressed body, concurrently with the real forward. The provider-counted answer is paired with the same response's billed usage — provider-authoritative savings receipts ('would have cost N, billed M') instead of local tokenizer estimates, shown as verified_savings on /status. The probe never mutates or delays the forwarded request; failures degrade to the estimate. Default false (one extra free HTTP call per compressed request)

Default false

Cache-safe cross-provider reasoning-effort control (#834). off (default) = no-op. minimal|low|medium|high pins the model's reasoning depth across providers: lean-ctx translates it to OpenAI reasoning_effort / reasoning.effort, Anthropic output_config.effort, and Gemini thinkingConfig (thinkingLevel on 3.x, thinkingBudget on 2.5 pro/flash), only on models that accept it and only when the client didn't set its own value. The level is a constant, so it never breaks the provider prompt cache (unlike per-turn effort routing). Anthropic is dialed only when the client already requested adaptive thinking

Default "off"

Custom upstream URL for Gemini API proxy

Default null

History pruning strategy. cache-aware: frozen boundaries that keep provider prompt caches valid (default). rolling: legacy moving window (max raw savings, breaks prompt caching). off: never prune

Default "cache-aware"

Live-compress non-protected tool_result content on the wire (#481). Default true. Set false for a meter-only proxy — real billed/cache token metering with zero request rewriting (combine with history_mode = "off" and no role_aggressiveness for a byte-unchanged body)

Default true

Tool-name patterns (case-insensitive substring) whose tool_result is never live-compressed — treated as protected, like a file read (#481). Unset protects Serena's code-reading tools; set an explicit list to narrow it, or [] to disable

Default ["serena"]

Inject stream_options.include_usage into streamed OpenAI Chat Completions so the final chunk reports real token usage for the measured spend meter. Default true

Default true

Custom upstream URL for OpenAI API proxy

Default null

Fraction 0.0-1.0 of conversations placed in the output-savings control arm (#895). 0 (default) = no holdout (every conversation is output-shaped). When > 0, a deterministic cohort = blake3(system + first user message) puts ~this fraction in a control arm that skips output-shaping (effort control + verbosity steer) but is still metered, yielding an honest measured output-token reduction (lean-ctx output-savings). The cohort is a pure function of conversation identity, so a conversation keeps one arm across all turns - cache-safe

Default 0

How the proxy squeezes prose it must shrink (#895). auto (default) and extractive use embedding-based extractive ranking — keeping the most central sentences instead of just the prefix — when the local embedding engine is available, else fall back to truncation; truncate keeps the original deterministic FIFO squeeze and never loads the engine. Wire rewrites are memoized per content so the engine's cold→warm transition never changes an already-emitted frozen-region rewrite (cache-safe, #448/#498)

Default "auto"

Opt-in cache-safe wire verbosity steer (#895). When true, the proxy appends a single constant 'be concise' instruction to the last user turn of each request - output-shaping for raw API clients that do not load lean-ctx rules. The suffix is constant and appended strictly after the last cache_control breakpoint (a new trailing text block, never modifying a cache-anchored block), so the provider prompt-cache prefix stays byte-stable. Under an output_holdout the control arm skips it so its effect is measured. Default false

Default true

Opt-in prose compression intensity (0.0–1.0) for system prompts in the proxy's frozen request region. Unset = leave untouched. Higher = more aggressive. Cache-safe (deterministic, never touches the client-cached prefix)

Default null

Opt-in prose compression intensity (0.0–1.0) for free-text user turns (never tool results) in the proxy's frozen request region. Unset = leave untouched

Default null

Number of BM25 candidates to retrieve before fusion

Default 75

BM25 lexical search weight in RRF fusion

Default 1

Number of dense candidates to retrieve before fusion

Default 75

Enable the dense (embedding) retrieval path. false → hybrid search ranks with BM25 + graph + rerank (+ SPLADE) only, skipping the embedding engine and the persistent embeddings.json (lighter footprint, no embed latency). An explicit mode=dense query still forces dense.

Default true

Dense vector search weight in RRF fusion

Default 1

SPLADE expansion weight (0.0 to disable)

Default 0.5

Additional regex patterns to detect as secrets

Default []

Enable secret/credential detection in tool outputs

Default true

Subtractive allowlist: matches covered by these regexes are never reported or redacted (#718)

Default []

Redact detected secrets from output

Default true

How to enforce the floor: redact (mask spans) or drop (withhold item)

Default "redact"

Enable the per-item sensitivity policy floor (no-op when false)

Default false

Block items at/above this level: public|internal|confidential|secret

Default "secret"

Inject agent rule files during setup/update. null=auto (inject if already present), true=always, false=never

Default null

Install SKILL.md files during setup/update. null=auto (install if rules present), true=always, false=never

Default null

Register lean-ctx MCP server in editor configs during setup/update

Default true

Master switch for the skillify miner (codify recurring session patterns into .cursor/rules). Only acts when explicitly invoked.

Default true

Minimum confidence for a single curated knowledge fact to be codified without repetition (0.0..=1.0).

Default 0.699999988079071

Minimum reinforcements (confirmations / repeated mentions) before a sub-threshold-confidence pattern is codified.

Default 2

Where generated rules are written: project (<repo>/.cursor/rules, git-committable) or global (~/.cursor/rules).

Default "project"

Enable solution-efficiency guidance

Default true

Inject solution-efficiency guidance into composed context

Default true

Inject solution-efficiency guidance into MCP instructions

Default true

Inject solution-efficiency guidance into subagent prompts

Default true

How strongly solution-efficiency guidance is applied

Default "balanced"

Include platform-native solution hints

Default true

Track solution decisions for efficiency guidance

Default true

Track lines of code changed for solution-efficiency guidance

Default true

Enable cross-project pattern analysis (commercial)

Default false

Enable solution fingerprint prediction (commercial)

Default false

Enable adaptive intensity ML model (commercial)

Default false

Learning rate for adaptive intensity model

Default 0.1

Minimum observations before adaptive recommendations

Default 20

Enable team-wide solution policy enforcement (commercial)

Default false

Minimum solution intensity enforced for team members

Default "balanced"

Require decision logging for all team members

Default false

Record periodic, semantically-recallable AI session summaries (what was done, files, decisions).

Default true

Tool calls between automatic session summaries (gated by the auto-checkpoint cadence).

Default 25

Maximum session summaries kept per project (oldest pruned first).

Default 100

Enable anonymous telemetry heartbeat (version, OS, arch, random install ID — no code or PII)

Default false

Enable automatic updates (requires explicit opt-in)

Default false

How often to check for updates (hours)

Default 6

Only notify about updates, don't install automatically

Default false