Configuração

O LeanCTX funciona pronto para uso, sem configuração. Todas as opções abaixo são opcionais - os valores padrão são ajustados para fluxos de trabalho típicos de desenvolvimento assistido por IA.

Arquivo de Configuração

O LeanCTX suporta um arquivo de configuração TOML opcional em ~/.lean-ctx/config.toml.

Criar a configuração padrão

lean-ctx config init

Ver configuração atual

lean-ctx config

Definir valores individuais

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

Opções de Configuração

Variáveis de Ambiente

Exclusão de redirecionamento do hook

O comando lean-ctx hook redirect intercepta chamadas nativas das ferramentas Read/Grep/ListFiles e as redireciona para as ferramentas lean-ctx MCP. Para excluir caminhos específicos deste redirecionamento (por exemplo, para fluxos de trabalho de Edit ou arquivos de protocolo do framework), use a opção de configuração redirect_exclude ou a variável de ambiente 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.

Regra do Cursor

Para economia máxima de tokens, adicione um .cursor/rules/lean-ctx.mdc ao seu projeto. Isso instrui o LLM a preferir ferramentas do LeanCTX e usar padrões de saída compactos. Um exemplo está incluído em examples/lean-ctx.mdc no repositório.

A regra do Cursor inclui o CRP v2 (Protocolo de Resposta Compacta) que pode reduzir tanto tokens de saída (50–80%) quanto tokens de raciocínio (30–60%) por meio de análise estruturada de tarefas e raciocínio de hipótese única. Esses intervalos são estimativas por resposta e dependem do modelo e da complexidade da tarefa.

Configuração de Autonomia

A camada de inteligência autônoma executa pipelines de otimização automaticamente. Configure em ~/.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

Sobrescreva com variável de ambiente: LEAN_CTX_AUTONOMY=false desativa tudo.

All Autonomy Fields

Filtros TOML do Usuário

Defina regras de compressão personalizadas em ~/.lean-ctx/filters/*.toml. Filtros do usuário são aplicados antes dos padrões 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 = ""

Gerencie via CLI: lean-ctx filter list, lean-ctx filter validate, lean-ctx filter init (cria exemplo).

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 Saída

No modo hook do shell (-c), o LeanCTX encaminha o código de saída do comando executado. Isso garante que scripts e pipelines de CI funcionem corretamente. Se o comando falhar (código de saída diferente de zero), a saída original completa é salva em ~/.lean-ctx/tee/ para depuração (quando tee_mode está definido como failures ou always).

Contagem de Tokens

O lean-ctx usa tiktoken-rs com a codificação o200k_base (a mesma do GPT-4o, Claude e outros modelos modernos) para contagem exata de tokens. Sem estimativas, sem heurísticas - cada número de economia que você vê em lean-ctx gain ou no dashboard reflete contagens reais de tokens.