Budgets, Roles & SLOs

LeanCTX tracks token usage per session and provides two monitoring systems: Budget Warnings (role-based limits) and SLO Violations (service level objectives). Both help you stay aware of context consumption.

What is BudgetWarning?

A BudgetWarning event fires when your session token usage reaches 80% of the configured limit (default: 200,000 tokens → warning at ~160,000). This appears in the Observatory as budget · {role} tokens {percent}% WARNING.

What is SessionContextTokens?

A separate SloViolation event fires when total session tokens exceed the SLO threshold (default: 200,000). This appears as violated · SessionContextTokens. Unlike BudgetWarning, SLOs are configured independently and can track additional metrics.

Key Difference

Both measure the same token counter but with different thresholds. BudgetWarning fires at 80% (early warning), while SessionContextTokens fires at 100% (actual violation).

Configuring Roles

Roles define budget limits. Create a file in ~/.lean-ctx/roles/ or <project>/.lean-ctx/roles/:

[limits]
max_context_tokens = 500000
max_shell_invocations = 200
max_cost_usd = 10.0
warn_at_percent = 90
block_at_percent = 255  # 255 = never block

Activate the role:

ctx_session action=role value=heavy

Configuring SLOs

SLOs are defined in slos.toml (searched in ~/.lean-ctx/ and <project>/.lean-ctx/):

[[slo]]
name = "context_budget"
metric = "session_context_tokens"
threshold = 500000
direction = "max"
action = "warn"

[[slo]]
name = "compression_quality"
metric = "compression_ratio"
threshold = 40.0
direction = "min"
action = "warn"

Reload after editing:

ctx_session action=slo value=reload

Available SLO Metrics

Default Values

Built-in Roles

LeanCTX ships with default roles: coder, reviewer, debugger, ops, admin. View the active role with ctx_session action=role.

Resetting Budgets

Reset the token counter mid-session with ctx_session action=reset. Switch roles with ctx_session action=role value=<name> (also resets the budget). Reload SLOs after editing with ctx_session action=slo value=reload.

# Reset token counter
ctx_session action=reset

# Switch role (also resets budget)
ctx_session action=role value=heavy

# View current role and budget
ctx_session action=role

# Reload SLOs after editing slos.toml
ctx_session action=slo value=reload

# View SLO violation history
ctx_session action=slo value=history

Blocking Mode

By default, budgets only warn (never block). To enable hard blocking, set block_at_percent = 100 in your role file. The default 255 means "never block".

[limits]
max_context_tokens = 200000
warn_at_percent = 80
block_at_percent = 100  # tools will be blocked at 100%