Journeys

Journey: Customization & Governance

Shape how LeanCTX behaves and enforce the rules you care about: compression levels, tool profiles, roles, filters and hardening that apply to every tool call.

Journey 19Operate & GovernRouteGovern

You aretuning behavior & enforcing rules

Covers

compression
tools
profile
config
theme
filter
rules
harden

LeanCTX ships with sensible defaults, but everything is tunable: how aggressively it compresses, which tools your agent sees, how output looks, and what rules your team enforces. This journey covers every knob and every governance surface, the “make it behave exactly how we want” journey.

Looking for the security surface (PathJail, shell allowlist, secret redaction, sandbox, harden, role policies)? That’s Security & Governance. This journey is about behavior tuning; that one is about guardrails.

1. Compression level — the master dial

One command sets how hard LeanCTX works to save tokens.

lean-ctx compression               # show current level + active components
lean-ctx compression standard      # set it (alias: lean-ctx terse standard)

Level	When to use
`off`	debugging LeanCTX itself; you want raw output
`lite`	default — plain, concise prose; maximum fidelity, light savings
`standard`	balanced — denser symbolic “power mode” output
`max`	aggressive — smallest context, densest agent prompts

Default: lite (compression_level = "lite"). lite keeps the model’s prose plain and readable; standard/max switch on the denser symbolic styles. This dial controls the model’s output style, not LeanCTX’s own tool-output compression (which is always on).

Each level is not a single switch, it expands into four coordinated components (shown by lean-ctx compression):

Component	Values
Agent prompt	off / lite / full / ultra
Output density	normal / terse / ultra
CRP mode	the agent response-compression profile
Token-model tuning	matched to the level

Setting a level also injects the matching compression prompt into your rules files so the agent itself responds tersely. Restart the agent/IDE to apply.

Overrides (most specific wins)

LEAN_CTX_COMPRESSION=standard      # per shell session (env)

# .lean-ctx.toml (per project)
compression_level = "standard"

So you can run max globally but pin one tricky repo to lite without touching global config.

2. MCP tool profiles — what your agent can see

Fewer tools = fewer tokens spent on tool definitions and less agent confusion. lean-ctx tools chooses which ctx_* tools are exposed.

lean-ctx tools                     # show active profile
lean-ctx tools lean                # the default — 13 lazy-core tools
lean-ctx tools reset               # back to the lean default
lean-ctx tools standard            # the balanced everyday set (~20 tools)
lean-ctx tools power               # the full 76-tool catalog
lean-ctx tools list                # list tools per profile

Profile	Tools	Best for
`lean`	13 lazy-core (default)	everyday use — the rest of the catalog loads on demand
`minimal`	~5	small models / strict token budgets
`standard`	~20	a broader everyday set
`power`	all (76)	code-intelligence + multi-agent + context-engineering work

Default: a fresh install pins no tool_profile — the exposed surface is 13 lazy-core tools, and the rest of the 76-tool catalog loads on demand (ctx_call / ctx_expand). Manage it explicitly with lean-ctx tools lean / lean-ctx tools reset; widen to everything with lean-ctx tools power. See the MCP tool map for exactly which tool sits in which profile.

Golden output — lean-ctx tools shows the active profile, the exact tool count, and where the value came from (so the lean default is verifiable):

Tool Profile: lean (default)
  Tools exposed: 13
  Description:   Lean core — full 76-tool catalog on demand
  Source:        default (lazy-core)

  Switch with: lean-ctx tools <lean|minimal|standard|power>

Source: default (lazy-core) is the fallback described above — no tool_profile was set, so the lean 13-tool surface is in effect and ctx_call / ctx_expand reach the rest of the catalog on demand.

3. Context profiles — saved tuning presets

Where tools picks the tool surface, profile saves a full tuning preset (compression + behavior) you can switch between.

lean-ctx profile list              # available context profiles
lean-ctx profile active            # which one is active
lean-ctx profile show <name>       # inspect a profile
lean-ctx profile diff <a> <b>      # compare two
lean-ctx profile create <name>     # snapshot current settings as a profile
lean-ctx profile set <name>        # activate

Use this to keep, say, a review profile (high fidelity) and a bulk profile (max compression) and flip between them per task.

“TOOL PROFILES” (tools) and “CONTEXT PROFILES” (profile) are different axes — §2 controls which tools, §3 controls how they behave.

4. The config file — every setting in one place

lean-ctx config                    # dump effective config
lean-ctx config show               # human-readable
lean-ctx config init               # write a starter config.toml
lean-ctx config schema             # full key reference
lean-ctx config validate           # check a config for errors
lean-ctx config set <key> <value>  # set one key
lean-ctx config apply              # apply changes to a running daemon

After editing config that the daemon reads, run lean-ctx restart (Lifecycle & Troubleshooting) so the daemon reloads. Full key list: Paths, env vars & config.

5. Themes — terminal output styling

lean-ctx theme list                # available themes
lean-ctx theme set <name>          # apply
lean-ctx theme export / import     # share a theme

Purely cosmetic (colors of CLI output); no effect on what’s sent to the agent.

6. Custom compression filters

Beyond the built-in compressors, you can define project-specific filters that strip or reshape command output.

lean-ctx filter list               # configured filters
lean-ctx filter init               # scaffold a filter config
lean-ctx filter validate           # check filter definitions

Use this when a tool your team runs produces noisy output that the generic compressor doesn’t handle well.

7. Governance — `rules`

For teams, the agent rules files (AGENTS.md, .cursor/rules, etc.) are configuration that should be version-controlled and kept in sync.

lean-ctx rules status              # are rules present & current?
lean-ctx rules init                # create governed rules
lean-ctx rules diff                # local vs. canonical
lean-ctx rules lint                # validate rules
lean-ctx rules sync                # bring rules up to date

This makes “every dev’s agent follows the same rules” enforceable rather than hoped-for.

Promote learned knowledge into rules

lean-ctx export-rules              # high-confidence knowledge → rules files

This turns durable facts your sessions discovered (Memory & Knowledge) into persistent agent rules, closing the loop from “learned once” to “always known”.

Context policy packs — governance as code

Beyond per-repo rules, a context policy pack is a versioned, declarative contract for how context is governed — redaction strength, allowed tools, role scopes, budgets — that travels with the repo and is enforced rather than hoped-for.

lean-ctx policy list                            # built-in + project packs
lean-ctx policy show <id>                        # inspect a resolved pack
lean-ctx policy validate                         # check .lean-ctx/policy.toml
lean-ctx policy coverage --framework eu-ai-act   # map active controls to a framework

Built-in packs cover common postures (baseline, strict-redaction, finance-eu, healthcare, open-source); a project .lean-ctx/policy.toml inherits one and overrides only what differs. lean-ctx policy coverage scores your active controls against the Context Governance Benchmark (CGB) and maps them to a framework (EU AI Act / ISO 42001 / SOC 2), so a security review starts from a generated coverage report instead of a blank page. The signed evidence behind that report lives in the Prove It journey.

8. Security hardening — `harden`

By default LeanCTX encourages agents to use ctx_* tools. harden makes it enforced by denying native Read/Grep in the agent’s MCP config.

lean-ctx harden                    # soft: set LEAN_CTX_HARDEN=1 in MCP configs
lean-ctx harden --hard             # also add Bash to Claude Code permissions.deny
lean-ctx harden --undo             # revert everything

After hardening, native Read/Grep are denied (except immediately after an Edit, so edit-verify still works). This guarantees token discipline across a team rather than relying on each agent’s goodwill.

Safety reference: lean-ctx safety-levels prints the compression safety-level table (what each level is allowed to drop), so you can audit exactly what hardening + a given compression level will and won’t strip.

9. Decision guide

You want…	Reach for
Save more / fewer tokens globally	`compression` (§1)
Limit which tools the agent sees	`tools` (§2)
Switch between tuning presets per task	`profile` (§3)
Change a single setting precisely	`config set` (§4)
Recolor CLI output	`theme` (§5)
Tame one noisy command’s output	`filter` (§6)
Enforce shared agent rules across a team	`rules` + `export-rules` (§7)
Force token discipline (deny native reads)	`harden` (§8)

Storage & config (customization)

Path / key	Controls
`config.toml` `compression_level`	global compression level
`.lean-ctx.toml` `compression_level`	per-project override
`LEAN_CTX_COMPRESSION` (env)	per-session override
`LEAN_CTX_HARDEN=1` (env, set by `harden`)	deny native reads
`config.toml` profile/tool-profile keys	active profiles