io.github.shreyassaw5394/agent-theatre

Agent Theatre

Watch your coding agent work — as a film, not a log.

Agent Theatre turns a Claude Code session into an animated scene. Your repo becomes a stage: folders are districts, files are buildings, test files are beacons. The agent is a character — one of a cast of twelve — who walks to the files it reads, builds on the files it edits, runs tests at the beacons, and chases bug gremlins when they fail. Subagents arrive at the dock as other members of the cast. Live, or replayed from any past session.

Twenty stages. Agent Theatre reads what your repo is — a web app, a backend, a CLI, data work, a game, infrastructure — and suggests the stages that suit it: Island, Orbit, Metropolis, Harbour, Observatory, Greenhouse, Workshop, Arcade, Kingdom, Outpost, Snowfield, Canopy, Lagoon, Volcano, Cloudtop, Reef, Bazaar, Monastery, Moonbase, Lanterns. Or hit Surprise me.

And one honest detail no other visualiser has: if the agent says the job is done but no test has passed since the last edit, a gremlin hides behind it.

Same session, different stages, different leads. The picker reads your repo and suggests three.

Six bundled episodes, each a different kind of work in a different repo — all synthetic, hand-written, never a captured session:

Watch them at agenttheatre.dev or locally with ?demo=research, ?demo=feature, ?demo=refactor, ?demo=deploy, ?demo=subagents.

Status

v1.0.0 — on npm as agent-theatre, VS Code extension on every release, six playable episodes at agenttheatre.dev. Live via hooks and replay of real sessions both verified end-to-end on real repos. Design notes in docs/design.md.

Install

Pick whichever fits how you work. All of them run the same local stage; nothing leaves your machine.

First run (CLI):

cd your-repo
npx agent-theatre hooks install   # once — skip if you installed the Claude Code plugin, it brings the hooks
npx agent-theatre                 # opens the stage for this repo; run Claude Code in another terminal
npx agent-theatre replay          # pick any past Claude Code session of this repo and watch it
npx agent-theatre hooks uninstall # reverses the install byte-for-byte

Flags: --port <n>, --no-open, --set <stage-id>; replay --latest skips the picker. Global install if you prefer: npm i -g agent-theatre.

In the stage: hover anything for what it is and what happened to it this session. Live stages show Live at the edge and a Go live button whenever you have scrubbed back. Whole repo pulls back to every building (wheel to zoom). Export clip records what you see and hear to mp4/webm with a share sheet (download, system share, X, LinkedIn). When the agent needs you, the stage says so and points you back to Claude Code (in VS Code it focuses the Claude Code input); you answer there, never on the stage. A stage watches the folder it was started in; several stages at once (browser, VS Code, another repo) all receive events.

MCP tools

agent-theatre serve is an MCP server (stdio). Any MCP client can:

Listed on the MCP Registry as io.github.shreyassaw5394/agent-theatre.

How it works

Claude Code ──hooks──▶ agent-theatre (local) ──WebSocket──▶ browser / VS Code webview
     │                        │
     └─ JSONL transcript ─────┘  (replay)

1. Events. Hook payloads (live) or transcript rows (replay) are normalised into a small, product-agnostic AgentEvent schema: read_file, edit_file (+n −m), run_command (intent), test_result, subagent_start/stop, waiting_for_user, turn_end, …
2. Stage. The repo's file tree becomes a deterministic arrangement — one of six layout archetypes (ring, grid, strip, scatter, terrace, spine) chosen from the repo and the stage, so the same project is a ring island in one set and a terraced spine in another, and always the same in the same set. Capped to ~60 buildings by relevance; every file the session touches is always placed.
3. Director. Events become scene beats — walk_to, build, run_tests, spawn_gremlin, chase, celebrate, unverified_claim — with a mood: curious, focused, lost, happy.
4. Renderer. PixiJS, isometric, soft lighting, easing everywhere — no linear tween exists in the codebase, a test makes sure. The camera frames the action; the whole stage appears only to open, celebrate and close, so it never gets cluttered. One key light: long soft cast shadows, gradient faces with ambient occlusion and rim light, aerial haze on far rows, bloom only on lamps and lit windows, cloud shadows drifting over the ground. prefers-reduced-motion respected. Twenty stages, each with its own silhouette — gabled harbour houses, pagoda tiers, onion domes, moonbase capsules, bazaar tents — on the same geometry; a cast of twelve characters from one procedural routine.
5. Sound. Every beat has a sound, all synthesized at runtime with the Web Audio API — no audio files, no licences to worry about. Every stage has its own voice (waveform, pitch, decay, the surface underfoot) and its own ambience — washes, pads and occasional details like gulls, bells, bubbles, wind or market murmur on a jittered timer, so nothing loops. Effects and background ambience toggle separately. The "needs your permission" chime is the one you'll notice.

Privacy

Everything stays on your machine. The event stream never contains code, prompts, command text or search queries — only repo-relative paths, counts, a command's first word and a classified intent. This is a tested invariant (packages/core/tests/privacy.test.ts plants secrets in a fixture session and asserts none reach the stream).

The server binds to 127.0.0.1 only. Hooks exit 0 and never block or slow your agent.

Repo layout

packages/core (schema, adapters, island, director — no DOM, no fs) · packages/cli · packages/web · packages/vscode · fixtures/ (synthetic sessions).

Community

Questions, stages worth showing off, ideas for v2: Agent Theatre Discord. The whole suite (LastSearch, Debug Anything, Agent Theatre) also shares one server.

Site

agenttheatre.dev — the story, a playable Episode 1, all twenty stages, the cast, the privacy sheet and install notes. agenttheatre.com redirects there. The site is site/ in this repo, deployed on Vercel from main; the playable demo is the real web bundle at /theatre/.

License

MIT © 2026 Shreyas Sawant and Agent Theatre contributors.