配置

LeanCTX 开箱即用，零配置。以下所有设置都是可选的--默认值已针对典型的 AI 辅助开发工作流进行优化。

配置文件

LeanCTX 支持位于 ~/.lean-ctx/config.toml 的可选 TOML 配置文件。

创建默认配置

lean-ctx config init

查看当前配置

lean-ctx config

设置单个值

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

配置选项

环境变量

Hook 重定向排除

lean-ctx hook redirect 命令拦截原生 Read/Grep/ListFiles 工具调用并将其重定向到 lean-ctx MCP 工具。要将特定路径排除在重定向之外（例如用于 Edit 工作流或框架协议文件），请使用 redirect_exclude 配置选项或 LEAN_CTX_HOOK_EXCLUDE 环境变量。

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

# Or via environment variable (takes precedence)
export LEAN_CTX_HOOK_EXCLUDE=".wolf/**,.claude/**,*.json"

Agent Integration Modes

lean-ctx init --agent <tool> supports three integration modes: cli-redirect (CLI-first), mcp (explicit ctx_* tools), and hybrid (both). auto selects the best default per tool.

# Auto (recommended)
lean-ctx init --agent cursor

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

# Force CLI-first
lean-ctx init --agent cursor --mode cli-redirect

# Best of both worlds
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.

Cursor 规则

为获得最大 token 节省，在项目中添加 .cursor/rules/lean-ctx.mdc。这指示 LLM 优先使用 LeanCTX 工具并使用紧凑输出模式。仓库中 examples/lean-ctx.mdc 包含一个示例。

Cursor 规则包含 CRP v2（紧凑响应协议），可通过结构化任务解析和单假设推理减少输出 token（50–80%）和思考 token（30–60%）。这些范围是每响应估算值，取决于模型和任务复杂度。

自主配置

自主智能层自动运行优化流水线。在 ~/.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 = 300   # Minimum seconds between consolidations

通过环境变量覆盖：LEAN_CTX_AUTONOMY=false 禁用所有。

All Autonomy Fields

用户 TOML 过滤器

在 ~/.lean-ctx/filters/*.toml 中定义自定义压缩规则。用户过滤器在内置模式之前应用。

# ~/.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 = ""

通过 CLI 管理：lean-ctx filter list、lean-ctx filter validate、lean-ctx filter init（创建示例）。

Security Layer v3.1.3

Security

lean-ctx 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.

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 Reciprocal Rank Fusion (RRF) for eviction. Each entry is ranked independently by recency, frequency, and size - then fused into a single score. Entries with the lowest RRF score are evicted first. No manual tuning required.

Progressive Throttling / Loop Detection

lean-ctx 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. lean-ctx 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. lean-ctx 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 = 6     # block after this many
window_secs = 300         # sliding window in seconds
search_group_limit = 10   # total search calls before block

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 lean-ctx 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: false)
threshold_chars = 4096        # Minimum characters before archiving (default: 4096)
threshold_tokens = 500        # Minimum tokens before archiving kicks in (default: 500)
max_age_hours = 48            # Auto-cleanup after N hours (default: 48)
max_disk_mb = 500             # Maximum total disk usage for archive (default: 500)
ttl_minutes = 120             # Per-entry auto-cleanup interval (default: 120)
exclude_tools = ["ctx_tree"]  # Tools whose output is never archived
always_archive = ["ctx_shell", "ctx_search"]  # Tools always archived above threshold
mask_secrets = true           # Redact secrets before archiving (default: true)

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.

Compaction Resilience v3.3.3

IDEs like Cursor and Windsurf periodically compact (truncate) conversation history to stay within context limits. When this happens, the agent loses all prior context - cached files, knowledge, session state. The [compaction] block controls how lean-ctx automatically recovers.

How It Works

1. lean-ctx detects a compaction event (conversation history is shorter than expected)
2. A resume summary is generated from the session diary, knowledge base, and cached files
3. The summary is injected into the next tool response so the agent can continue seamlessly

Configuration

# ~/.lean-ctx/config.toml
[compaction]
auto_detect = true            # Automatically detect compaction events (default: true)
resume_max_tokens = 500       # Maximum tokens for the resume summary (default: 500)
include_archives = true       # Include archive references in resume (default: true)
include_knowledge = true      # Include knowledge base entries in resume (default: true)

Example Recovery Flow

# After compaction, the next tool call automatically includes:
# --- COMPACTION RECOVERY ---
# Session: 45 calls, 3 files cached
# Active task: Refactoring auth module
# Key decisions: JWT over sessions (see knowledge #12)
# Archives: [ARC:a1b2c3] auth.rs full output
# ---

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 = "standard"    # off | lite | 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 lean-ctx'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 lean-ctx'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 lean-ctx 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, lean-ctx 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]]
name = "test"
command = "cargo test --workspace --quiet"

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

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

Headless MCP Mode v3.3.3

By default, when lean-ctx 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 lean-ctx instructions via --append-system-prompt
• Toggle setups - You want to switch lean-ctx on/off per session
• CI/CD pipelines - No interactive environment, no need for hooks
• Sandboxed environments - You don't want lean-ctx modifying files outside the project

退出码

在 shell hook 模式（-c）下，LeanCTX 转发被包装命令的退出码。这确保脚本和 CI 流水线正常工作。如果命令失败（非零退出），完整的原始输出会保存到 ~/.lean-ctx/tee/ 以供调试（当 tee_mode 设置为 failures 或 always 时）。

Token 计数

lean-ctx 使用 tiktoken-rs 的 o200k_base 编码（与 GPT-4o、Claude 和其他现代模型相同）进行精确 token 计数。无估算，无启发式方法--你在 lean-ctx gain 或仪表盘中看到的每个节省数字都反映真实的 token 计数。