Configuration

LeanCTX works out of the box with zero configuration. All settings below are optional - defaults are tuned for typical AI-assisted development workflows.

Config File

LeanCTX supports an optional TOML configuration file at ~/.lean-ctx/config.toml.

Create the default config

lean-ctx config init

View current configuration

lean-ctx config

Set individual values

lean-ctx config set ultra_compact true
lean-ctx config set checkpoint_interval 15
lean-ctx config set tee_mode always
lean-ctx config set passthrough_urls localhost:3000,api.internal

Validate Your Config

# Check for typos, unknown keys, and wrong field names
lean-ctx config validate

# View the full config schema (all keys, types, defaults)
lean-ctx config schema

Configuration Priority

When the same setting is defined in multiple places, LeanCTX uses a clear priority order. Higher-priority sources override lower ones:

Within a single config file, TOML is a key-value format; there is no line-order priority. If you define the same key twice, the TOML parser will use the last occurrence, but this is considered a syntax error. Use lean-ctx config validate to catch such issues.

Common Confusion: "max" Parameters

LeanCTX has several parameters with "max" in their name that control completely different things. This table clarifies which parameter controls what:

Config Options

Simplified Configuration v3.6.18

Instead of tuning dozens of individual limits, you can set a few high-level parameters that automatically derive downstream values. When simplified settings are used and individual limits are still at their defaults, the derived values take effect.

Use lean-ctx config show to see all effective values with their source (env / config / default / derived).

# Example: 2GB disk budget → facts=800, patterns=200, episodes=2000, procedures=400
max_disk_mb = 2000
compression_level = "Standard"
max_staleness_days = 30

Environment Variables

Hook Redirect Exclusion

The lean-ctx hook redirect command intercepts native Read/Grep/ListFiles tool calls and redirects them to LeanCTX MCP tools. To exclude specific paths from this redirect (e.g. for Edit workflows or framework protocol files), use the redirect_exclude config option or the LEAN_CTX_HOOK_EXCLUDE environment variable.

# ~/.lean-ctx/config.toml
redirect_exclude = [".wolf/**", ".claude/**", "*.json", "CLAUDE.md"]

Agent Integration Modes

lean-ctx init --agent <tool> supports two --agent values: hybrid (MCP reads + shell hooks, recommended) and mcp (explicit ctx_* tools only). auto selects the best default per tool (Hybrid for agents with shell access, MCP for others). A third integration mode, CLI-Redirect, removes MCP entirely and drives LeanCTX through editor rules.

# Auto (recommended — selects Hybrid for most agents)
lean-ctx init --agent cursor

# Force MCP tools only
lean-ctx init --agent cursor --mode mcp

# Force Hybrid (MCP reads + shell compression)
lean-ctx init --agent cursor --mode hybrid

Binary File Passthrough (v2.21.0)

The hook redirect automatically detects binary files (images, PDFs, archives, fonts, videos, compiled files) by extension and passes them through to the native Read tool. This ensures AI agents can still view screenshots, images, and other non-text files without interference.

Shadow Mode v3.7.0

Shadow Mode transparently intercepts native Read, Grep, and Shell tool calls via IDE hooks and routes them through lean-ctx's compression and caching layer. This provides full token savings without requiring the agent to explicitly call ctx_read/ctx_search/ctx_shell.

How it works

1. When enabled, lean-ctx strengthens MCP instructions to MUST-level routing directives
2. Bypass hints trigger on the first native tool use (not after 5 calls) with stronger "intercepted" wording
3. All intercepted calls are logged to ~/.lean-ctx/shadow.log for audit transparency
4. Redirected output includes a header explaining the interception

Configuration

# Enable shadow mode
lean-ctx config set shadow_mode true

# Or via environment variable
export LEAN_CTX_SHADOW_MODE=true

Visibility

Shadow mode status is visible in:

• lean-ctx status — shows "shadow_mode: active" when enabled
• lean-ctx doctor — validates hook wiring for interception
• ~/.lean-ctx/shadow.log — full audit trail of intercepted calls

When to use

• Agents that ignore MCP tool instructions and keep using native Read/Grep
• Automated pipelines where you cannot control the agent's tool choice
• Teams wanting guaranteed token savings without agent cooperation

Cursor Rule

For maximum token savings, add a .cursor/rules/lean-ctx.mdc to your project. This instructs the LLM to prefer LeanCTX tools and use compact output patterns. An example is included in examples/lean-ctx.mdc in the repository.

The Cursor rule includes CRP v2 (Compact Response Protocol) which can reduce both output tokens (50–80%) and thinking tokens (30–60%) through structured task parsing and one-hypothesis reasoning. These ranges are per-response estimates and depend on the model and task complexity.

Autonomy Configuration

The autonomous intelligence layer runs optimization pipelines automatically. Configure in ~/.lean-ctx/config.toml:

[autonomy]
enabled = true                    # Master switch for all autonomy features
auto_preload = true               # Pre-cache imported files after ctx_read
auto_dedup = true                 # Auto-deduplicate at 8+ cached files
auto_related = true               # Suggest related files via import graph
auto_consolidate = true           # Auto-consolidate knowledge periodically
silent_preload = true             # Cache files without output
dedup_threshold = 8               # Files before auto-dedup triggers
consolidate_every_calls = 25      # Run consolidation every N tool calls
consolidate_cooldown_secs = 120   # Minimum seconds between consolidations
cognition_loop_enabled = true     # Background cognition loop (periodic knowledge consolidation)
cognition_loop_interval_secs = 3600  # Seconds between cognition-loop iterations
cognition_loop_max_steps = 8      # Maximum steps per cognition-loop iteration

Override with environment: LEAN_CTX_AUTONOMY=false disables all.

All Autonomy Fields

Multi-Root Workspaces v3.7.0

LeanCTX supports working across multiple repositories from a single parent directory. There are two approaches:

Auto-detection (no config needed)

If your working directory has 2 or more child directories with project markers (.git, Cargo.toml, package.json, etc.), LeanCTX auto-detects it as a multi-repo workspace and indexes everything under the parent.

# Just cd into the parent — LeanCTX handles the rest
cd ~/code
lean-ctx status
# → project_root: /Users/you/code (multi-repo workspace)

extra_roots (explicit configuration)

For repos in different locations, or fine-grained control over which repos are indexed:

# ~/.lean-ctx/config.toml
extra_roots = [
    "/Users/you/work/api",
    "/Users/you/work/frontend",
    "/Users/you/oss/cool-lib",
]

# Or per-project in .lean-ctx.toml:
extra_roots = ["../shared-infra", "../common-types"]

How indexing works

• Primary root: Indexed first (synchronous for first tool call)
• Extra roots: Indexed in background threads after primary completes
• Deduplication: Extra roots inside the primary root are skipped (already covered)
• Storage: Each root gets its own ~/.lean-ctx/graphs/<hash>/ directory

For a detailed walkthrough with troubleshooting, see the Multi-Repo Workspace journey.

User TOML Filters

Define custom compression rules in ~/.lean-ctx/filters/*.toml. User filters are applied before builtin patterns.

# ~/.lean-ctx/filters/my-api.toml
name = "My API filter"
commands = ["curl"]

[[rules]]
pattern = "X-Request-Id: [a-f0-9-]+"
replacement = ""

[[rules]]
pattern = "^\\s+$"
replacement = ""

Manage via CLI: lean-ctx filter list, lean-ctx filter validate, lean-ctx filter init (creates example).

Security Layer v3.1.3

Security

LeanCTX enforces these security boundaries automatically. No configuration needed - they are always active:

PathJail (Project-Root Sandbox)

Every file operation is validated through a single resolve_path choke point. Paths must resolve inside the project root - symlink attacks, ../ traversal, and absolute paths outside the project are rejected. The sandbox is enforced for ctx_read, ctx_edit, ctx_search, ctx_tree, and all other file-touching tools.

Size Caps

Prompt Injection Hardening

All metadata in tool responses is sanitized via neutralize_metadata - stripping control characters, encoded sequences, and injection patterns. Sensitive output blocks (knowledge, memory, gotchas) are wrapped in CSPRNG-fenced boundaries to prevent prompt injection through LLM-generated content stored in memory.

TOCTOU Mitigation

ctx_edit uses the same file handle for read-verify-write, preventing time-of-check-to-time-of-use race conditions where a file could be swapped between the validation and write phases.

Secret Detection v3.6.0

The [secret_detection] section configures regex-based secret detection in tool outputs. When enabled, LeanCTX scans all tool responses for patterns matching API keys, tokens, passwords, and other sensitive values.

Configuration

# ~/.lean-ctx/config.toml
[secret_detection]
enabled = true                # Enable regex-based secret detection (default: true)
redact = true                 # Automatically redact detected secrets (default: true)
custom_patterns = []          # Additional regex patterns for detection (default: [])

Boundary Policy v3.6.0

The [boundary_policy] section controls cross-project access behavior. In monorepo or multi-project setups, this determines whether agents can search or import files across project boundaries, and whether such access is logged for audit.

Configuration

# ~/.lean-ctx/config.toml
[boundary_policy]
cross_project_search = false      # Allow searching across project boundaries (default: false)
cross_project_import = false      # Allow importing knowledge from other projects (default: false)
audit_cross_access = true         # Log an audit event on cross-project access (default: true)
universal_gotchas_enabled = true  # Load universal (cross-project) gotchas (default: true)

Data Directory v3.1.3

All persistent data (stats, knowledge, agent state, sessions, cache) is stored under a single base directory, resolved in this order:

1. LEAN_CTX_DATA_DIR environment variable (if set)
2. ~/.lean-ctx (default)

# Override for custom locations or containers
export LEAN_CTX_DATA_DIR=/data/lean-ctx

# Verify current data directory
ls "$(lean-ctx config | grep data_dir)"

CLI File Cache v2.21.1

Since v2.21.1, lean-ctx read <file> in CLI mode caches file content to $LEAN_CTX_DATA_DIR/cli-cache/cache.json (default: ~/.lean-ctx/cli-cache/cache.json). Subsequent reads of unchanged files return a compact ~13-token cache-hit response instead of the full file content. This enables caching for CLI-mode integrations (e.g. pi-lean-ctx) that don't use the MCP server.

Management Commands

lean-ctx cache              # Overview with hit rate
lean-ctx cache stats        # Detailed statistics
lean-ctx cache clear        # Remove all entries
lean-ctx cache invalidate <path>  # Remove specific file

lean-ctx read file.rs --fresh     # Bypass cache for one read

Cache Eviction Policy

The session cache uses a multi-signal eviction system: Reciprocal Rank Fusion (RRF) fuses recency, frequency, and size into a base score. On top, Hebbian co-access patterns track which files are used together, and a Boltzmann temperature mechanism adjusts eviction aggressiveness based on memory pressure. Entries with the lowest combined energy are evicted first. No manual tuning required.

Progressive Throttling / Loop Detection

LeanCTX automatically detects when an AI agent loops - calling the same or similar tools repeatedly without progress. This prevents token waste in large and monorepo projects.

Per-Fingerprint Throttling

Tool calls are tracked using a fingerprint-based sliding window (default 5 minutes). When repeated identical calls are detected, throttling escalates:

Cross-Tool Search Tracking v3.1.2

Agents often alternate between ctx_search, ctx_shell (grep/rg/find), and ctx_semantic_search to search for the same thing. LeanCTX now tracks ALL search-related calls as a group. If more than 10 total search calls happen within the window (regardless of which tool), the agent is blocked with guidance to use ctx_tree and narrow searches with the path parameter.

Pattern Similarity Detection v3.1.2

Searching for "compress", then "compression", then "compress_output" is now detected as the same semantic loop. LeanCTX extracts the alpha-root of each search pattern and groups similar queries together.

Configuration

All thresholds are configurable via ~/.lean-ctx/config.toml:

[loop_detection]
normal_threshold = 2      # warn after this many identical calls
reduced_threshold = 4     # reduce output after this many
blocked_threshold = 0     # block after this many (0 = disabled)
window_secs = 300         # sliding window in seconds
search_group_limit = 10   # total search calls before block

# Per-tool total call ceilings within one session (0 = unlimited)
[loop_detection.tool_total_limits]
ctx_read = 100
ctx_search = 80
ctx_semantic_search = 60
ctx_shell = 50

Pipe Guard v2.21.6

Since v2.21.6, the shell hook automatically detects when stdout is piped (not a terminal) and bypasses all compression. This prevents corruption when piping command output - for example, curl -fsSL https://example.com/install.sh | sh now works correctly even with the LeanCTX shell hook active.

Tool Result Archive v3.3.3

When compression removes details you might need later, the Tool Result Archive saves the full uncompressed output to disk and returns a reference ID. The agent can retrieve the full content at any time using ctx_expand.

This is the core of zero-loss compression: the context window stays small, but no information is permanently lost.

How It Works

1. A tool response exceeds the configured token threshold
2. LeanCTX stores the full output to ~/.lean-ctx/archive/ (content-addressed by SHA-256)
3. The compressed response includes an [ARCHIVE: <id>] reference
4. The agent calls ctx_expand <id> to retrieve the full content on demand

Configuration

# ~/.lean-ctx/config.toml
[archive]
enabled = true                # Enable tool result archiving (default: true)
ephemeral = true              # Replace large results with summary + ref, retrievable via ctx_expand (default: true)
ephemeral_min_tokens = 2000   # Minimum output tokens before the ephemeral firewall fires (default: 2000)
threshold_chars = 800         # Minimum characters before archiving (default: 800)
max_age_hours = 48            # Auto-cleanup after N hours (default: 48)
max_disk_mb = 500             # Maximum total disk usage for archive (default: 500)

Environment Variables

Storage

Archived results are content-addressed (SHA-256 hash of the full output). Duplicate content is automatically deduplicated. Race conditions from parallel tool calls are handled via PID-unique temporary files with atomic rename.

Compression Level v4.0.0

compression_level is the unified control for the 4-layer terse engine, replacing the legacy output_density and terse_agent settings. It governs both input compression (tool responses) and output optimization (agent responses) through a single knob.

Levels

Configuration

# ~/.lean-ctx/config.toml
compression_level = "lite"    # lite (default) | off | standard | max

# Legacy settings still accepted for backward compatibility:
# terse_agent = "full"            # maps to compression_level = "standard"
# output_density = "terse"        # maps to compression_level = "lite"

Environment Variables

Interaction with CRP Mode

compression_level and LEAN_CTX_CRP_MODE are complementary but independent. CRP mode controls the format of LeanCTX's own output (tdd/compact/off), while compression_level controls both input compression and the instructions given to the agent about how it should respond. Both can be active simultaneously for maximum token savings.

What Changes (Standard / Max)

When compression is active at "standard" or above, the 4-layer terse engine applies:

• Layer 1: Dictionary — Common token substitutions and abbreviations
• Layer 2: Residual — Whitespace normalization, boilerplate removal
• Layer 3: Scoring — Information-theoretic ranking of content blocks
• Layer 4: Pipeline — CEP v1 protocol with delta-only output, structured notation (+/-/~), and token budgets

This can reduce total token usage by 30-50% per conversation turn. Formally verified by 82 Lean4 theorems including TerseQuality and TerseEngine proofs.

Legacy: Terse Agent Mode

The terse_agent setting is still accepted for backward compatibility. Values are mapped automatically: "off" → Off, "lite" → Lite, "full" → Standard, "ultra" → Max. Boolean true maps to Standard.

Legacy: Output Density v3.1.0 — superseded by compression_level

output_density is superseded by compression_level, which unifies both input and output compression into a single setting. The legacy output_density values are still accepted and mapped automatically: "normal" → Off, "terse" → Lite, "ultra" → Max.

Legacy Configuration

# ~/.lean-ctx/config.toml
# Legacy (still works):
output_density = "terse"

# Recommended replacement:
compression_level = "lite"

Minimal Overhead v3.4.1

minimal_overhead reduces LeanCTX's per-call token footprint to the absolute minimum. It's designed for environments where every token counts - Codex, CI pipelines, or any cost-sensitive workflow.

What it disables

Configuration

# ~/.lean-ctx/config.toml
minimal_overhead = true

# Or via environment variable
# export LEAN_CTX_MINIMAL=1

# To only disable checkpoints (keep other meta-strings):
# export LEAN_CTX_NO_CHECKPOINT=1

When to use

• Codex / Claude Code CLI - these environments benefit most from reduced overhead since every token in the conversation counts against the context window
• CI/CD pipelines - automated tasks where meta-strings add noise without value
• High-frequency tool calls - sessions with many short tool calls where per-call overhead accumulates
• Cost optimization - when you want to minimize API costs without changing compression settings

Measured impact

Combined with lazy tools (default), minimal overhead reduces per-session token overhead from ~6,600 tokens (full tools + verbose) to ~2,400 tokens (lazy + minimal) - a 64% reduction.

Rules Scope v3.3.3

Controls where LeanCTX injects its cursor rules file (lean-ctx.mdc). By default, rules are injected in both the global and project locations to ensure coverage across all Cursor workspaces.

Values

Configuration

# ~/.lean-ctx/config.toml
rules_scope = "global"    # global | project | both

# Set via CLI
lean-ctx config set rules_scope project

Buddy Mode

Buddy mode enables collaborative multi-agent workflows. When enabled, LeanCTX coordinates context sharing between multiple agent sessions working on the same project.

Configuration

# ~/.lean-ctx/config.toml
buddy_enabled = true

Custom Aliases

Define custom shell command aliases that expand inside ctx_shell. Useful for project-specific shortcuts that agents can use without knowing the full command.

Configuration

# ~/.lean-ctx/config.toml
[[custom_aliases]]
alias = "test"
command = "cargo test --workspace --quiet"

[[custom_aliases]]
alias = "lint"
command = "npm run lint -- --fix"

[[custom_aliases]]
alias = "deploy-staging"
command = "kubectl apply -f k8s/staging/ --dry-run=client"

Headless MCP Mode v3.3.3

By default, when LeanCTX starts as an MCP server it automatically configures the environment: injecting rules, installing hooks, updating CLAUDE.md, and registering itself. If you want full control over your configuration - for example when using a custom launcher - you can disable all auto-setup behavior.

Usage

# Set before launching the MCP server
export LEAN_CTX_HEADLESS=1

# lean-ctx will start as a pure MCP server:
# - No rules injection
# - No hook installation
# - No CLAUDE.md modification
# - No agent registry updates
# - No background version check

When to Use

• Custom launchers - You inject LeanCTX instructions via --append-system-prompt
• Toggle setups - You want to switch LeanCTX on/off per session
• CI/CD pipelines - No interactive environment, no need for hooks
• Sandboxed environments - You don't want LeanCTX modifying files outside the project

Project Identity File (.lean-ctx-id) v3.5.16

LeanCTX identifies projects by hashing their root path. In Docker or CI environments where multiple projects share the same mount path (e.g. /workspace), this can cause data collisions, graph index, semantic cache, bandit state, and embedding index from one project bleeding into another.

To prevent this, create a .lean-ctx-id file in your project root with a unique project name. This file takes highest priority for project identification, above git remote URL, package.json name, and directory name.

# Create the identity file
echo "my-unique-project-name" > .lean-ctx-id

Priority Order

Identity-Aware Caches

The following data stores use a composite project hash (path + identity) to ensure isolation:

• Graph index, project dependency graph (SQLite Property Graph)
• Semantic cache, embedding-based similarity lookups
• Bandit state, multi-armed bandit model for read mode selection
• Embedding index, vector store for semantic search

When a .lean-ctx-id file is added or changed, existing data is automatically migrated from old hash directories. No manual action required.

Docker Usage

# Include in your Dockerfile or mount as volume
COPY .lean-ctx-id /workspace/.lean-ctx-id

# Or create during build
RUN echo "my-project" > /workspace/.lean-ctx-id

Shell Activation v3.5.16

shell_activation controls when LeanCTX shell aliases (like _lc) auto-activate in interactive shells. By default, LeanCTX activates in every shell. In team environments or CI, you may want to limit activation to AI agent sessions only.

Modes

# ~/.lean-ctx/config.toml
shell_activation = "agents-only"    # always | agents-only | off

# Or via environment variable
# export LEAN_CTX_SHELL_ACTIVATION=agents-only

# ~/.lean-ctx/config.toml
[cloud]
contribute_enabled = false    # Opt-in to anonymous usage telemetry (default: false)

# ~/.lean-ctx/config.toml
[providers]
enabled = true            # Enable/disable all providers
auto_index = true         # Index into BM25/Graph/Knowledge (not just cache)
cache_ttl_secs = 120      # In-memory TTL for provider results

# MCP bridge — HTTP transport
[providers.mcp_bridges.knowledge-base]
url = "http://localhost:8080"

# MCP bridge — stdio transport
[providers.mcp_bridges.github-mcp]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
auth_env = "GITHUB_TOKEN"

export JIRA_OAUTH_CLIENT_ID=...        # from your Atlassian 3LO app
export JIRA_OAUTH_CLIENT_SECRET=...    # from your Atlassian 3LO app
export JIRA_AUTH=oauth                 # optional: force OAuth over Basic auth

lean-ctx provider auth jira            # one-time interactive consent

# ~/.lean-ctx/config.toml
[proxy]
anthropic_upstream = null     # Custom Anthropic API endpoint (default: null)
openai_upstream = null        # Custom OpenAI API endpoint (default: null)
gemini_upstream = null        # Custom Gemini API endpoint (default: null)
history_mode = "cache-aware"  # History pruning: cache-aware (default) | rolling | off
allow_insecure_http_upstream = false  # Allow a trusted plaintext http:// upstream (default: false)

# ~/.lean-ctx/config.toml
[embedding]
model = "minilm"          # minilm (384d, default) | jina-code-v2 (768d) | nomic (768d) | hf:org/repo
auto_download = true      # Download the model in the background on first semantic need (default: allowed)

[memory.knowledge]
max_facts = 200               # Maximum stored facts per project (default: 200)
max_patterns = 50             # Maximum code patterns (default: 50)
max_history = 100             # Maximum history entries (default: 100)
contradiction_threshold = 0.5 # Confidence threshold for contradiction detection (default: 0.5)
recall_facts_limit = 10       # Facts recalled per retrieval (default: 10)
rooms_limit = 25              # Maximum rooms returned (default: 25)
timeline_limit = 25           # Maximum timeline entries (default: 25)
relations_limit = 40          # Maximum relations returned (default: 40)

[memory.episodic]
max_episodes = 500            # Maximum stored episodes (default: 500)
max_actions_per_episode = 50  # Actions per episode (default: 50)
summary_max_chars = 200       # Episode summary length (default: 200)

[memory.procedural]
max_procedures = 100          # Maximum stored procedures (default: 100)
min_repetitions = 3           # Repetitions before a pattern becomes a procedure (default: 3)
min_sequence_len = 2          # Minimum sequence length for detection (default: 2)
max_window_size = 10          # Maximum window size for pattern analysis (default: 10)

[memory.lifecycle]
decay_rate = 0.01             # Daily decay factor for memory scores (default: 0.01)
low_confidence_threshold = 0.3 # Below this, facts are low-confidence (default: 0.3)
stale_days = 30               # Days before an entry is considered stale (default: 30)
similarity_threshold = 0.85   # Cosine similarity for deduplication (default: 0.85)

[memory.gotcha]
max_gotchas_per_project = 100       # Maximum gotchas per project (default: 100)
retrieval_budget_per_room = 10      # Gotchas surfaced per session (default: 10)
default_decay_rate = 0.03           # Default decay rate for gotcha importance (default: 0.03)

[memory.embeddings]
max_facts = 2000              # Maximum facts in the embedding index (default: 2000)