Context SLOs

Define Service Level Objectives for your context metrics. SLOs are evaluated after every tool call and trigger actions when thresholds are exceeded.

Configuration

Create a slos.toml file in your .lean-ctx directory to define custom SLOs. Default SLOs are provided if no file is found.

# .lean-ctx/slos.toml
[[slo]]
name = "context_budget"
metric = "session_context_tokens"
threshold = 50000
action = "warn"  # warn | throttle | block

[[slo]]
name = "cost_per_session"
metric = "session_cost_usd"
threshold = 1.00
action = "throttle"

[[slo]]
name = "compression_efficiency"
metric = "compression_ratio"
threshold = 0.3
direction = "min"
action = "warn"

Available Metrics

SLO Actions

MCP Commands

ctx_session slo              # Show current SLO status
ctx_session slo reload       # Reload SLOs from disk
ctx_session slo history      # Show violation history
ctx_session slo clear        # Clear violation log

Anomaly Detection

Automatically detects unusual token consumption patterns per agent and project, alerting when significant deviations from normal behavior occur.

How It Works

lean-ctx uses Welford’s online algorithm to maintain running statistics for each metric:

• Exponential moving average (EMA) over a sliding window of 50 tool calls
• Alert triggers at >3x standard deviation from the mean
• Events are emitted and visible in the TUI and dashboard

Tracked Metrics

Currently tracks tokens_per_call with automatic recording after every tool invocation.

Prometheus Metrics

Export all observability data in Prometheus text format for integration with Grafana, Datadog, or any monitoring stack.

Endpoint

# Start dashboard with metrics endpoint
lean-ctx dashboard

# Scrape metrics
curl http://localhost:3000/metrics

Available Metrics

lean_ctx_tokens_saved_total
lean_ctx_compression_ratio
lean_ctx_session_cost_usd
lean_ctx_tool_calls_total
lean_ctx_slo_violations_total
lean_ctx_cache_hit_rate
lean_ctx_anomalies_total
lean_ctx_session_uptime_seconds

Grafana Integration

Point your Prometheus scraper at the /metrics endpoint. A Grafana dashboard template is planned for a future release.

Zero-PII Guarantee

Only counters, gauges, and ratios are exported. No file contents, paths, session data, or any personally identifiable information is ever included in metrics.

Session Diffing

Compare two sessions side-by-side to understand how context evolved between coding sessions.

Usage

# Compare two sessions (MCP)
ctx_session diff <session_a> <session_b>
ctx_session diff <session_a> <session_b> json

# List available sessions
ctx_session list

What Gets Compared

The diff engine compares the full session structure:

• Files touched: added, removed, mode changes
• Findings: new discoveries vs previous session
• Decisions: architectural choices made
• Statistics: tool calls, tokens saved, commands run

Dashboard API Endpoints