Advanced Features

Deep dive into LeanCTL's compression engine, context management, MCP integration, task routing, and other power-user features.

Compression Engine

LeanCTL integrates the LeanCTX compression engine to reduce token usage across all interactions.

Compression levels

Tool output compression is automatically adjusted based on your provider's cost:

Level	Provider	File threshold	Search threshold	Command threshold
Minimal	Ollama, free	200 lines	80 matches	5,000 chars
Standard	Groq, DeepSeek	80 lines	30 matches	2,000 chars
Aggressive	Anthropic, OpenAI	50 lines	15 matches	1,000 chars

For read_file at Aggressive level, files are compressed to API signatures (function signatures, exports, dependencies). At Minimal level, you get more raw content.

Command output compression

The run_command tool recognizes 90+ CLI tools across 34 categories and applies pattern-specific compression:

• git (19 patterns): status, log, diff, commit, push, pull, branch, etc.
• npm/yarn/pnpm: install, test, build, audit
• cargo: build, test, clippy
• docker: build, compose, logs, ps
• kubectl: get, describe, logs, apply
• Test runners: jest, vitest, pytest, go test, rspec
• Linters: eslint, biome, prettier, ruff, tsc
• And 50+ more (terraform, helm, make, maven, gradle, flutter, etc.)

Unrecognized commands get entropy-based compression when savings exceed 15%.

Message compression

When the conversation grows beyond 6 messages, older messages are compressed. The compression level matches your provider cost — expensive providers get more aggressive compression to save money.

Context Management

LeanCTL actively manages the context window to prevent overflow and optimize token usage.

Auto-compact

When context utilization exceeds 85%, LeanCTL automatically compresses the conversation using a summary LLM call. This keeps the most recent 4 messages intact while summarizing older context.

Threshold	Action
70%	Warning in status bar
80%	Second warning
85%	Auto-compact triggered (if auto_compact = true)
90%	Critical warning
95%	Emergency warning

Manually trigger with /compact or Ctrl+X C. Add a focus term to guide the summary: /compact auth.

Circuit breaker

If auto-compact fails 3 times consecutively (empty summary), the circuit breaker opens and stops further compact attempts until reset. This prevents infinite compression loops.

Auto-dedup

Every 15 tool loops, cross-file deduplication runs automatically. It analyzes cached files for redundant content and removes duplicates to free context space.

Loop Detection

LeanCTL has multiple layers of protection against AI loops:

Mechanism	Trigger	Action
Tool loop limit	25 iterations per turn	Turn terminated
Fingerprint detector	Same tool + args 3 times in 5-call window	Call blocked with guidance
LeanCTX throttle	Progressive (5 warnings, 12 blocked)	Warning, then block

Task Routing

Route different task types to different providers for optimal cost/quality balance:

[routing]
explore = "local"       # fast local model for file reads, search
generate = "claude"     # strong model for code generation
casual = "local"        # local model for casual questions
fallback = ["gpt"]      # try these if primary fails

How routing works

1. LeanCTL classifies your prompt into a task type (explore, generate, debug, etc.)
2. The router looks up which provider to use from your [routing] config
3. If the provider fails, it tries each entry in the fallback list
4. Sub-agents always use the explore route (lightweight, read-only)

Route names must match entries in your [[providers]] registry. Format: "name" (use name's model) or "name/specific-model" (override model).

MCP Integration

LeanCTL can connect to external MCP (Model Context Protocol) servers, extending the AI's capabilities with custom tools.

Configuration

# In ~/.leanctl/config.toml
[mcp.my-server]
command = "my-mcp-binary"
args = ["--port", "3000"]

[mcp.my-server.env]
API_KEY = "secret"

TUI management

/mcp                              # show MCP server status
/mcp add my-server my-mcp-binary  # add a new server
/mcp reload                       # reconnect all servers

How it works

• MCP tools are prefixed with mcp_servername_ to avoid name conflicts
• LeanCTL spawns MCP servers as child processes and communicates via JSON-RPC over stdio
• Tool calls have a 30-second timeout
• MCP tool permissions default to "Dangerous" (always requires confirmation)
• MCP servers are initialized at startup from your config and can be added at runtime

Session Management

LeanCTL stores chat sessions in a local SQLite database at ~/.leanctl/sessions/sessions.db.

Features

• Auto-title: Sessions are automatically titled based on the first user message
• Per-project: Sessions are scoped to the project root, so each project has its own history
• Token tracking: Input, output, and thinking tokens are stored per turn
• Search: Find sessions by title content
• Resume: Continue any previous session with full message history

CLI

leanctl sessions       # list recent sessions
leanctl -C             # continue most recent session
leanctl resume         # same as -C

TUI

/sessions              # browse with interactive picker (Ctrl+S)
/resume 3              # resume session #3
/delete 5              # delete session #5
/export                # export current chat as markdown (Ctrl+X X)

LITM Optimization

LeanCTL uses "Lost in the Middle" (LITM) position optimization to place critical context where the AI is most likely to attend to it. Research shows that LLMs pay more attention to the beginning and end of the context, while content in the middle gets less attention.

LITM automatically reorders system prompt sections to maximize attention on the most relevant context for your current task. This is tuned per AI tool via profiles (configured with /lab LEAN_CTX_LITM_PROFILE).

Text Tool Parsing Fallback

If a model doesn't support native tool calling (or fails to produce valid tool calls), LeanCTL extracts tool calls from the text response. It recognizes:

• XML-style <tool_call> blocks
• JSON objects with tool name and parameters
• Code blocks that look like file writes
• Inline patterns matching known tools

This ensures tool use works even with models that only support text output.

Project Detection

At session start, LeanCTL automatically detects:

• Language/framework: via Cargo.toml, package.json, pyproject.toml, go.mod, etc.
• Git state: current branch, dirty status
• File tree: compact project structure (max 40 lines, depth 2)
• Lint/test/build commands: inferred from the detected language
• Instruction files: all supported instruction files are merged
• Skills: SKILL.md and skill directories are discovered

All this context is included in the system prompt to give the AI immediate understanding of your project.