ORCHESTRA
a governed terminal multiplexer for the Claude Code CLI
A terminal HUD that watches the Claude Code CLI from out-of-band taps and puts every permission decision in the operator's hands.
A control room for AI agents working in the terminal. You watch what each one is doing and approve anything risky before it runs.
- Phase 2 underway
- 2025-26
What it is
Running an AI agent in a terminal is like watching a black box. You see the output, but not what it is doing, what it costs, or whether it is stuck. Orchestra is the control room around it: it sits beside the agent, shows the whole picture at a glance, and puts every risky action behind a button you have to press. Nothing of consequence happens without your say-so.
The work
Context
A black box, made legible
Every Claude Code session is a black box. You see the output, not the cost, the tool sequence, or whether the agent is working, waiting, or stuck. I built Orchestra so I could run sessions unattended and read the machine's state at a glance when I came back.
Orchestra hosts the real interactive claude CLI inside a pseudo-terminal pane and overlays interpreted side panels built from structured taps. It is a terminal multiplexer, not a wrapper. The CLI runs exactly as it would in a normal terminal, and Orchestra watches from outside.
Architecture
Three layers, one source of truth
The pane layer hosts the real claude CLI in a pseudo-terminal, drives a pyte VT emulator with the byte stream, renders the screen, and forwards keystrokes. It interprets nothing, and that boundary is a design rule rather than a convention.
The interpretation layer takes structured events from two independent taps, a hooks server and an OTLP receiver, and normalises them into one internal vocabulary. State accumulates as the single source of truth for all four panels, and the hook and OTel views of the same tool call reconcile on a join key confirmed empirically.
Governance
Every risky action behind a gate
Observation is out of band. The hooks and OTel taps are invisible to the model, so there is no tool calling back to Orchestra that would add tokens to every turn or make observation depend on the model's cooperation. A hook fires deterministically on a lifecycle event.
The control layer is the gate. A PreToolUse hook blocks, the relay round-trips to Orchestra, and I approve, deny, or rewrite the call from the HUD. A matching permissions.deny rule beats a hook allow from the same settings file, and the destructive-class deny floor is platform-enforced.
What shipped
An observe-only HUD, proven on real runs
Phase 1 shipped the full observe-only HUD: four panels for activity, session status, token usage, and topology, a focus toggle, auth-mode display, and a responsive layout. The live exit test passed, the suite ran 131 passed and 1 skipped, and the type checker came back clean under strict mode.
The usage panel accumulated live token totals from a real session, and those numbers come from the Ledger export rather than being typed in. Phase 2, the gate, is underway in the current branch.
The GUI
The same model, a new surface
The HUD started in the terminal, which is the right place to watch a terminal agent. The next surface is graphical: the same out-of-band hook and OTel taps, the same four panels, and the same blocking gate, moved into a window instead of a pane.
The observation model does not change, only what it is drawn on.
The receipts
Every figure from a real run
The Ledger and the Eval now produce real exports, and every number on this site comes from one of them. The golden eval scorecard below is from a real run. A number that does not come from a real run is not a number.