Context Engine

Observatory & Dashboard

Monitor LeanCTX events, budgets, and compression in real-time with the Observatory.

The Observatory is LeanCTX's real-time monitoring system. It shows every event, tool calls, budget warnings, SLO violations, compression stats, as a live stream you can filter and inspect.

How to Access

There are two ways to open the Observatory:

Terminal (TUI)

Terminal

lean-ctx watch

Real-time event stream in your terminal. Filter with arrow keys, search with /.

Web Dashboard

Terminal

lean-ctx dashboard --open=vscode

Opens the full dashboard in your browser at http://127.0.0.1:3333. Includes all panels, charts, and the live event feed. Control how it reveals with --open=browser|none|vscode (or --no-open): none starts silently and just prints the URL, vscode prints the VS Code Simple Browser steps. Defaults to browser and also honors LEAN_CTX_DASHBOARD_OPEN.

Event Types

The Observatory shows these event categories:

Category	Icon	Examples
Tool Calls	`→`	`ctx_read`, `ctx_shell`, `ctx_search`
Compression	`↓`	File read compressed 84%, shell output compressed 72%
Budget	`$$`	BudgetWarning: tokens at 82%
SLO	`!!`	SessionContextTokens violated
Cache	`⚡`	Cache hit (13 tokens), cache miss
Session	`○`	Session start, role change, agent handoff
Autonomy	`⟡`	Auto-preload, auto-dedup, auto-related
Error	`✗`	Tool error, path jail violation, timeout

Budget & SLO Events

These events appear when token usage approaches configured limits. See Budgets & SLOs for how to tune thresholds.

14:32:05 $$ budget · coder tokens 82% WARNING

14:45:12 !! slo · context_budget violated · SessionContextTokens > 200000 → warn

14:45:12 ℹ hint: Occasional violations are normal; frequent ones may indicate a configuration issue.

Dashboard Panels

The web dashboard (lean-ctx dashboard) provides additional panels beyond the live event feed:

Overview

Session stats: tokens saved, compression ratio, tool calls, active time.

ROI & Plan

Measured spend — the real provider bill (real model + billed tokens) for proxy-routed clients, shown per model alongside the estimated cost analysis. See measured vs estimated.

Live Feed

Real-time event stream with filtering by category, severity, and text search, plus a Sort selector — Recent / Top saved / Largest / Slowest — to rank tool calls by cost and spot the expensive reads, searches, and shell calls at a glance.

Health

SLO status cards, green/red indicators for each configured SLO with current values.

Agents

Multi-agent view: token usage per agent, handoff history, context budgets.

Compression Lab

Per-file and per-tool compression breakdown. Identify which patterns save the most tokens.

Context Map

Visual graph of file relationships, import chains, and cross-source connections.

Quick Settings

Flip the four high-impact switches mid-session without dropping to the terminal: compression level, tool profile, structure_first, and terse agent. Writes persist to config.toml through an auth- and CSRF-guarded endpoint; values pinned by a LEAN_CTX_* env var are flagged so a toggle never silently no-ops.

REST API

The dashboard exposes a REST API for programmatic access:

Endpoint	Method	Description
`/api/events`	GET	Recent events (JSON array)
`/api/events/stream`	GET	Server-Sent Events (live stream)
`/api/slos`	GET	Current SLO status for all definitions
`/api/stats`	GET	Session statistics (tokens, compression)
`/api/agents`	GET	Active agents and their budgets
`/api/spend`	GET	Measured per-model provider bill (`source: "measured"`)
`/metrics`	GET	Prometheus-compatible metrics

Example: fetch current SLO status

curl http://127.0.0.1:3333/api/slos | jq