Agent Cockpit

Terminal dashboard that shows whether your AI agent is behaving, not just spending.

Tools like ccusage tell you how much a session cost. Agent Cockpit tells you what happened — did enforcement hooks fire? Is context still healthy? What pipeline step is it on? Which agents got delegated?

Think of it as btop for AI agent sessions.

Quick Start

# Zero-install run
uvx agent-cockpit demo          # see it with sample data

# Full install
pip install agent-cockpit
agent-cockpit setup             # install observer hooks (10 sec)
agent-cockpit                   # launch dashboard

What You See

Agent Cockpit reads Claude Code hook logs and displays six panels in a 2×3 grid:

Panel	What it shows
1 · Context Health	Token usage bar, percentage, cost, zone (green/yellow/red)
2 · Gates	Verdict sparkline (▲ pass, ▼ block, ◆ inject), ratio, recent events
3 · Hook Fires	Horizontal bar chart of hook fire frequency
4 · Agents	Active and recent delegations with model, type, background status
5 · Pipeline	Linear step tracker: read → plan → build → test → qc
6 · Tasks	Task list with status indicators (■ active, □ pending, ✓ done)

Keyboard

Key	Action
s	Cycle scope: session → today → all
1-6	Focus a panel
Esc	Return to grid view
q	Quit

How It Works

┌──────────────────────────────────────────────┐
│              Agent Cockpit TUI               │
│         (read-only, never modifies)          │
├──────────────────────────────────────────────┤
│              EventStore (ring buffer)        │
├──────────────────────────────────────────────┤
│ JSONL watcher │ JSON poller │ tmux scanner   │
├──────────────────────────────────────────────┤
│ enforcement   │ context     │ tasks          │
│ .jsonl        │ .json       │ directory      │
│ hook-fires    │ pipeline    │ tmux sessions  │
│ .jsonl        │ .json       │                │
│ delegation    │             │                │
│ .jsonl        │             │                │
└──────────────────────────────────────────────┘

Architecture principles:

• Read-only — Cockpit never writes to any file it reads. Zero side effects.
• Graceful degradation — Missing log files show "no data" panels, never crash.
• Zero-config first run — Auto-detects Claude Code log locations.
• Observer-only hooks — Bundled hooks log events but never block your agent (always exit 0).

All data sources are normalized to a unified CockpitEvent model at read time. The event store uses a bounded ring buffer (10K events) so memory stays constant regardless of session length.

Installation

Requirements: Python 3.12+

# Option A: Run without installing (recommended)
uvx agent-cockpit

# Option B: Install from PyPI
pip install agent-cockpit

# Option C: Install with faster JSON parsing
pip install agent-cockpit[fast]

Hook Setup

After installing, run the setup command to install observer hooks:

agent-cockpit setup

This creates a lightweight observer script at ~/.claude/scripts/cockpit-observer.sh and prints the settings.json entry to register it. The observer:

• Logs every tool use to ~/.claude/logs/hook-fires.jsonl
• Logs Agent delegations to ~/.claude/logs/delegation.jsonl
• Never blocks — always exits 0

Configuration

Agent Cockpit works out of the box with no configuration. It reads from standard Claude Code log locations:

Source	Path	Watch method
Enforcement verdicts	~/.claude/logs/enforcement.jsonl	File watcher
Hook fires	~/.claude/logs/hook-fires.jsonl	File watcher
Delegations	~/.claude/logs/delegation.jsonl	File watcher
Context state	~/.claude/logs/context.json	Polling (2s)
Pipeline state	~/.claude/logs/pipeline.json	Polling (2s)
Tasks	~/.claude/tasks/	Polling (2s)
Background agents	tmux sessions	Polling (5s)

Development

git clone https://github.com/zl190/agent-cockpit.git
cd agent-cockpit
uv run --extra dev pytest tests/ -v    # 87 tests, ~0.1s

The codebase follows a src layout:

src/agent_cockpit/
  events.py       — CockpitEvent dataclass + 6 normalizers
  store.py        — Ring buffer with session scoping
  sources/        — JSONL watcher, JSON poller, task reader, tmux scanner
  panels/         — 6 Textual TUI panels
  fixtures/       — Demo replay data
  app.py          — Textual App (2×3 grid, keyboard nav, 2s refresh)
  cli.py          — CLI entry point
  demo.py         — Fixture replay engine
  setup.py        — Hook installer

Roadmap

• 6-panel dashboard with live data
• Demo mode with sample data
• One-command hook setup
• Session history and cross-session comparison
• Sparkline charts for gate verdicts over time
• Decision minimap visualization

License

MIT