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

Opens the full dashboard in your browser at http://127.0.0.1:3333. Includes all panels, charts, and the live event feed.

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.

Seeing lots of these? Your token budget is too low for your workflow. See Budgets & SLOs to raise the limits.

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.

Live Feed

Real-time event stream with filtering by category, severity, and text search.

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.

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
`/metrics`	GET	Prometheus-compatible metrics

Example: fetch current SLO status

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