Environment Variables

lean-ctx behavior can be configured via ~/.lean-ctx/config.toml or environment variables. Env vars always take precedence over the config file, making them ideal for per-session overrides, CI/CD, and containerized environments.

All variables use the LEAN_CTX_ prefix (with a few LCTX_ exceptions for safety caps). Boolean variables accept true/false, 1/0, or simply being set/unset.

Core

Fundamental settings that control data storage, caching, output protocols, and checkpointing.

Examples

# Use a custom data directory (e.g. for containers)
export LEAN_CTX_DATA_DIR=/data/lean-ctx

# Increase cache TTL to 10 minutes
export LEAN_CTX_CACHE_TTL=600

# Switch to compact output mode
export LEAN_CTX_CRP_MODE=compact

# Checkpoint every 10 calls for maximum resilience
export LEAN_CTX_CHECKPOINT_INTERVAL=10

# Enable maximum compression on tool responses
export LEAN_CTX_OUTPUT_DENSITY=ultra

Shell

Control the shell hook behavior, timeouts, and shell binary selection.

Examples

# Temporarily disable lean-ctx for a session
export LEAN_CTX_DISABLED=1

# Get raw output for a single command
LEAN_CTX_RAW=1 lean-ctx -c "cat package.json"

# Set a 5-minute shell timeout
export LEAN_CTX_SHELL_TIMEOUT_MS=300000

# Force a specific shell binary (Windows)
export LEAN_CTX_SHELL="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe"

Tools & Agent

Configure tool availability, agent behavior, rules injection, and model selection.

Examples

# Inject rules only in the project directory
export LEAN_CTX_RULES_SCOPE=project

# Disable expensive tools to save tokens
export LEAN_CTX_DISABLED_TOOLS=ctx_benchmark,ctx_metrics,ctx_wrapped

# Enable full terse agent mode
export LEAN_CTX_TERSE_AGENT=full

# Start MCP in headless mode (no auto-setup)
export LEAN_CTX_HEADLESS=1

# Set model for accurate gain calculation
export LEAN_CTX_MODEL=claude-sonnet-4

Autonomy

Fine-grained control over lean-ctx's autonomous behaviors - preloading, deduplication, related file suggestions, and knowledge consolidation. All autonomy env vars override the corresponding [autonomy] section in config.toml.

Examples

# Disable all autonomy features
export LEAN_CTX_AUTONOMY=false

# Keep autonomy on but disable preloading
export LEAN_CTX_AUTO_PRELOAD=false

# Increase dedup threshold for large projects
export LEAN_CTX_DEDUP_THRESHOLD=15

# Consolidate less frequently
export LEAN_CTX_CONSOLIDATE_EVERY_CALLS=50
export LEAN_CTX_CONSOLIDATE_COOLDOWN_SECS=600

Tool Mode

Control how lean-ctx exposes its tools to the AI agent - lazy discovery, single-tool mode, or full tool listing.

Examples

# Enable lazy tool discovery
export LEAN_CTX_LAZY_TOOLS=1

# Use single-tool mode for minimal token overhead
export LEAN_CTX_UNIFIED=1

# Show all tools (debugging)
export LEAN_CTX_FULL_TOOLS=1

Dashboard (Observatory)

Configure the real-time Observatory dashboard binding and project selection.

Examples

# Run Observatory on a custom port
export LEAN_CTX_PORT=8080

# Expose dashboard in Docker
export LEAN_CTX_HOST=0.0.0.0

# Override project for dashboard
export LEAN_CTX_DASHBOARD_PROJECT=/home/user/my-project

Archive Premium

The Tool Result Archive enables zero-loss compression: full tool outputs are saved to disk, and the agent retrieves them on demand via ctx_expand. These env vars override the [archive] section in config.toml.

Examples

# Enable the archive system
export LEAN_CTX_ARCHIVE=true

# Only archive large outputs (8k+ chars)
export LEAN_CTX_ARCHIVE_THRESHOLD=8192

# Keep archives for 72 hours
export LEAN_CTX_ARCHIVE_TTL=72

# Disable archive for a session
export LEAN_CTX_ARCHIVE=0

Compaction Resilience Premium

Control how lean-ctx recovers when the IDE compacts (truncates) conversation history. These env vars override the [compaction] section in config.toml.

Examples

# Disable compaction recovery
export LEAN_CTX_COMPACTION_RESUME=0

# Keep default behavior (auto-resume after compaction)
unset LEAN_CTX_COMPACTION_RESUME

Safety Caps

These variables use the shorter LCTX_ prefix and control hard limits that prevent accidental resource exhaustion.

Examples

# Allow reading files up to 10 MB
export LCTX_MAX_READ_BYTES=10485760

# Increase shell output cap to 5 MB
export LCTX_MAX_SHELL_BYTES=5242880

Quick Reference

All environment variables at a glance, sorted alphabetically.