Configuration

LeanCTL stores its configuration in ~/.leanctl/config.toml. The init wizard creates this file — all settings below are optional.

Config File

View your current configuration:

leanctl config

The config file lives at ~/.leanctl/config.toml and has the following sections:

Full example

# ~/.leanctl/config.toml

# Default provider (used when starting leanctl)
default_provider = "murat"

# Provider registry — add as many as you need
[[providers]]
name = "murat"
type = "ollama"
model = "qwen3.5:27b"
base_url = "http://murat.local:11434"

[[providers]]
name = "claude"
type = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"

[[providers]]
name = "gpt"
type = "openai"
model = "gpt-4.1"
api_key_env = "OPENAI_API_KEY"

[[providers]]
name = "local"
type = "ollama"
model = "gemma4:e2b"

# Thinking configuration
[thinking]
mode = "auto"   # auto | always | never | manual

# Behavior settings
[behavior]
auto_preload = true       # auto-load project context
context_budget = 8000     # max tokens for context
confirm_edits = true      # ask before editing files
confirm_commands = true   # ask before running commands
auto_compact = true       # compress context automatically

# Display settings
[display]
show_thinking_budget = true
show_token_savings = true
show_cost = true
compact = false

# Theme
theme = "default"

# Task routing — use different models per task type
[routing]
explore = "local"       # fast local model for exploration
generate = "claude"     # strong model for code generation
casual = "local"        # local model for casual chat

# MCP servers (external tool integration)
[mcp.my-server]
command = "my-mcp-server"
args = ["--port", "3000"]

# Gateway (Pro features)
gateway_url = "https://api.leanctl.com"
gateway_key = "lctl_..."
tier = "pro"

Provider Registry

The [[providers]] array is the primary way to configure AI providers. Each entry defines a named provider with its type, model, and credentials.

See Providers for detailed setup instructions per provider.

Thinking Configuration

Controls how LeanCTL manages AI reasoning tokens. See Thinking Steering for the full guide.

Behavior Settings

Display Settings

Task Routing

Route different task types to different providers. This lets you use a fast local model for exploration and a powerful cloud model for code generation.

[routing]
explore = "local"       # file reads, searches, navigation
generate = "claude"     # code generation, refactoring
casual = "local"        # casual conversation
fallback = ["gpt"]      # fallback if primary fails

Provider names must match entries in your [[providers]] registry.

MCP Servers

Extend LeanCTL with external MCP (Model Context Protocol) servers:

[mcp.my-server]
command = "my-mcp-binary"
args = ["--port", "3000"]

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

Manage MCP servers in the TUI with /mcp, /mcp add, and /mcp reload.

Permissions

Control which tools require confirmation with a per-project .leanctl/permissions.toml:

# .leanctl/permissions.toml
write_file = "allow"      # auto-approve file writes
run_command = "deny"       # always block shell commands
git_commit = "allow"       # auto-approve commits
* = "allow"                # allow everything (same as --yolo)

Pattern matching supports wildcards (*) and prefix patterns (git_*). More specific patterns take precedence.

Environment Variables

LeanCTL also loads .env files from your project root automatically.

Project Configuration

Instruction files

LeanCTL reads project-specific instructions from any of these files (checked in order, all merged):

Instructions are truncated to 2,000 characters in the system prompt.

Skills discovery

LeanCTL discovers skill files from these paths and makes them available to the AI:

• SKILL.md — project root
• .leanctl/SKILL.md — project config
• .leanctl/skills/*.md — skill directory (recursive)
• .cursor/skills/*.md — Cursor skills compatibility

Custom commands

Create custom slash commands by adding markdown files to .leanctl/commands/ or ~/.leanctl/commands/:

# .leanctl/commands/review.md
Review the following code for security issues,
performance problems, and best practices.
Focus on: $ARGUMENTS

Usage in the TUI: /review src/auth.ts — the $ARGUMENTS placeholder is replaced with whatever follows the command name.

Lab Parameters

The /lab command in the TUI lets you tune LeanCTX compression parameters at runtime:

/lab                              # show all current values
/lab LEAN_CTX_CRP_MODE compact    # set CRP mode to compact
/lab LEAN_CTX_CACHE_TTL 600       # extend cache to 10 minutes

Themes

LeanCTL includes built-in theme presets. Switch in the TUI:

/theme              # open theme picker
/theme neon         # switch to neon theme

Create a custom theme file at ~/.leanctl/theme.toml to override colors.

Storage Locations