Documentation

Context Profiles

Declarative, version-controlled context strategies for lean-ctx

Context Profiles let you configure how lean-ctx processes content for different scenarios: exploration, debugging, hotfixes, CI, code review, and more. Think of it as "Context as Code" - version-controlled strategies your team can share.

What Are Profiles?

A profile is a TOML file that controls read modes, compression settings, token budgets, pipeline layers, and autonomy behavior. Profiles can inherit from other profiles and override specific fields.

Built-in Profiles

lean-ctx ships with 5 built-in profiles optimized for common workflows:

exploration

Broad context for understanding codebases. Map mode, 200K token budget, cache preferred.

bugfix

Focused debugging with auto mode. Standard compression, 100K token budget, 10-call checkpoints.

hotfix

Minimal context for urgent fixes. Signatures mode, ultra-compact output, 30K tokens, $1 cost cap.

ci-debug

CI/CD debugging with 200 shell invocations. Standard compression, 150K token budget.

review

Code review with broad read-only context. Map mode, compact CRP, 150K token budget.

Activating a Profile

Set the LEAN_CTX_PROFILE environment variable:

export LEAN_CTX_PROFILE=hotfix

Or use the CLI:

lean-ctx profile set hotfix

Or switch at runtime via MCP:

ctx_session action=profile value=hotfix

Creating Custom Profiles

Create a profile TOML file in .lean-ctx/profiles/ (project-local) or ~/.lean-ctx/profiles/ (global):

# .lean-ctx/profiles/my-team.toml
[profile]
name = "my-team"
inherits = "exploration"
description = "Team defaults with lower budget"

[read]
default_mode = "map"
max_tokens_per_file = 40000

[budget]
max_context_tokens = 120000
max_cost_usd = 2.0

Or use the CLI to scaffold a profile:

lean-ctx profile create my-team --from exploration

Profile Inheritance

Profiles can inherit from any other profile using the inherits field. Child values override parent values; unset fields fall through to the parent.

# .lean-ctx/profiles/strict-review.toml
[profile]
name = "strict-review"
inherits = "review"

[budget]
max_context_tokens = 80000
max_cost_usd = 1.0

Profile Schema

A complete profile has these sections:

  • [profile] - name, inherits, description
  • [read] - default_mode, max_tokens_per_file, prefer_cache
  • [compression] - crp_mode, compression_level, entropy_threshold
  • [budget] - max_context_tokens, max_shell_invocations, max_cost_usd
  • [pipeline] - intent, relevance, compression, translation (boolean toggles)
  • [autonomy] - auto_dedup, checkpoint_interval

CLI Reference

  • lean-ctx profile list - Show all available profiles
  • lean-ctx profile show <name> - Display profile details
  • lean-ctx profile diff <a> <b> - Compare two profiles
  • lean-ctx profile create <name> - Create a new profile
  • lean-ctx profile set <name> - Show activation instructions

Resolution Order

Profiles are resolved in this order:

  1. LEAN_CTX_PROFILE environment variable
  2. Project-local .lean-ctx/profiles/<name>.toml
  3. Global ~/.lean-ctx/profiles/<name>.toml
  4. Built-in defaults