Configuración

LeanCTX funciona de inmediato sin configuración. Todos los ajustes a continuación son opcionales - los valores predeterminados están optimizados para flujos de trabajo típicos de desarrollo asistido por IA.

Archivo de configuración

LeanCTX soporta un archivo de configuración TOML opcional en ~/.lean-ctx/config.toml.

Crear la configuración predeterminada

lean-ctx config init

Ver configuración actual

lean-ctx config

Establecer valores individuales

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

Opciones de configuración

Variables de entorno

Exclusión de redirección del hook

El comando lean-ctx hook redirect intercepta las llamadas nativas de herramientas Read/Grep/ListFiles y las redirige a las herramientas lean-ctx MCP. Para excluir rutas específicas de esta redirección (por ejemplo, para flujos de trabajo de Edit o archivos de protocolo del framework), usa la opción de configuración redirect_exclude o la variable de entorno 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.

Regla de Cursor

Para el máximo ahorro de tokens, agrega un archivo .cursor/rules/lean-ctx.mdc a tu proyecto. Esto instruye al LLM a preferir las herramientas de LeanCTX y usar patrones de salida compactos. Se incluye un ejemplo en examples/lean-ctx.mdc en el repositorio.

La regla de Cursor incluye CRP v2 (Compact Response Protocol) que puede reducir tanto los tokens de salida (50–80%) como los tokens de razonamiento (30–60%) a través del análisis estructurado de tareas y razonamiento de una hipótesis. Estos rangos son estimaciones por respuesta y dependen del modelo y la complejidad de la tarea.

Configuración de autonomía

La capa de inteligencia autónoma ejecuta pipelines de optimización automáticamente. Configura en ~/.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

Anula con variable de entorno: LEAN_CTX_AUTONOMY=false desactiva todo.

All Autonomy Fields

Filtros TOML de usuario

Define reglas de compresión personalizadas en ~/.lean-ctx/filters/*.toml. Los filtros de usuario se aplican antes que los patrones integrados.

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

Gestiona a través del CLI: lean-ctx filter list, lean-ctx filter validate, lean-ctx filter init (crea un ejemplo).

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

Códigos de salida

En modo shell hook (-c), LeanCTX reenvía el código de salida del comando ejecutado. Esto asegura que los scripts y pipelines de CI funcionen correctamente. Si el comando falla (código distinto de cero), la salida original completa se guarda en ~/.lean-ctx/tee/ para depuración (cuando tee_mode está configurado como failures o always).

Conteo de tokens

lean-ctx usa tiktoken-rs con la codificación o200k_base (la misma de GPT-4o, Claude y otros modelos modernos) para el conteo exacto de tokens. Sin estimaciones, sin heurísticas - cada número de ahorro que ves en lean-ctx gain o el panel refleja conteos reales de tokens.