Back to Browse

Agent Theatre MCP Server

Developer ToolsLow Risk9.5MCP RegistryLocal
Free

Server data from the Official MCP Registry

Watch your coding agent work as a film: opens and replays the Agent Theatre stage for a repo.

About

Watch your coding agent work as a film: opens and replays the Agent Theatre stage for a repo.

Security Report

9.5
Low Risk9.5Low Risk

Valid MCP server (2 strong, 2 medium validity signals). 1 known CVE in dependencies ⚠️ Package registry links to a different repository than scanned source. Imported from the Official MCP Registry. 1 finding(s) downgraded by scanner intelligence.

11 files analyzed · 2 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

network_websocket

Check that this permission is expected for this type of plugin.

clipboard

Check that this permission is expected for this type of plugin.

env_vars

Check that this permission is expected for this type of plugin.

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "agent-theatre": {
      "command": "npx",
      "args": [
        "-y",
        "agent-theatre"
      ]
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

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-one 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 — and, in the weeks around Halloween, Halloween: jack-o'-lanterns, bats, a ghost-white gremlin and the odd jump scare (switch them off with Scares in the toolbar). Or hit Surprise me.

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

Lanterns, Juno at login.ts

What did the agent change?

The Changes view turns the same session into a map of every file the agent touched: folders as blocks, files sized by lines changed and coloured by what happened (new, edited, deleted, read), plus anything changed during the session that the agent did not do (you, a formatter, another tool). Drag the time slider to see the map at any moment, filter to one helper, click a file for its diff, or copy the whole thing as Markdown for a pull request.

The Changes view: files the agent touched, by folder

  • At the end of every turn, Claude Code shows a one-line summary under the reply, e.g. this turn: 3 files changed (+50 −2) · 1 new · 1 deleted with a link to the map. Turn it off with AGENT_THEATRE_SUMMARY=0.
  • In the terminal: npx agent-theatre changes (--md for Markdown, --json, --reads).
  • On the pull request: npx agent-theatre changes --pr posts (or updates) one comment with the map, using your own gh login, after asking you.
  • In VS Code: an Agent changes list in the Explorer, a dot on every file the agent touched, and the editor's own diff on click.

Built from the agent's own events and checked against git, so shell edits (sed -i, heredocs, rm) are confirmed on disk before they appear, and changes committed mid-session still count. Paths and line counts only; a diff is read from your disk only when you open it.

Island, NimbusOrbit, RookVolcano, Ember
Harbour, Mo and a helper at the dockKingdom, the full appThe set picker

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:

EpisodeKindWhat happens
The login timeoutbug fixtwo failing tests, one grace window, a green run — and the evidence chip
The research briefresearchfield notes, a data file, two web searches, one written brief; no tests claimed
The export endpointnew featuretwo new buildings rise, a route is wired, the suite is green first time
The renamerefactorsix files touched, one test catches a slip, fifty-eight pass
Ship 1.4.0deployall shell work at the forge: build, plan, a timeout, a retry, a rollout, a tag
The audithelperstwo helpers arrive at the dock and fan out while the lead keeps working

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

Status

v1.6.0 — the Changes map; 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 on your machine. It talks only to 127.0.0.1, except when you post a change map to GitHub yourself (changes --pr).

WhereHowNotes
npm (CLI)npx agent-theatreNode 22+. npx agent-theatre replay for past sessions
Claude Code plugin/plugin install agent-theatre --marketplace shreyassaw5394/agent-theatreone step on Claude Code 2.1.275+; brings the hooks, a /theatre command and a skill
Homebrewbrew install shreyassaw5394/tap/agent-theatretap: shreyassaw5394/homebrew-tap
VS Codesearch Agent Theatre in Extensions, or Marketplacecommands: Open the stage (live), Replay a session…, Switch folder. .vsix also on every release
Cursor / Windsurf / VSCodiumagent-theatre.vsix from the latest release → Extensions → ⋯ → Install from VSIX…same extension; Open VSX listing coming
MCP server (Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI, VS Code Copilot)npx agent-theatre initregisters agent-theatre serve with every agent on your machine; --repo writes .mcp.json / .cursor/mcp.json / .vscode/mcp.json for the team. One-click: Cursor VS Code
Just watchagenttheatre.devsix synthetic episodes, no install

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 changes         # what the agent touched: files, lines, new, deleted (--md, --pr)
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). Full screen (or F) keeps just the stage and the transport bar. 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. When the agent goes quiet the stage says so: after ~20 s "thinking…", after 90 s the house lights dim, the lead sits down, ambience thins and a banner counts the silence; the moment an event arrives it all comes back. When the session ends, the banner says so. 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:

ToolDoes
open_stagestart (or reuse) the live stage for a folder → URL
list_sessionspast Claude Code sessions of a folder: ids, titles, times
replay_sessionopen a replay of one session (newest by default) → URL
stage_statusevent/beat counts and the last few event kinds; never contents
what_changedthe change map: files read, edited, created, deleted, with line counts; Markdown for a PR on request
install_hooksinstall the Claude Code hooks (not needed with the plugin)

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 in the folder that the session touches is always placed. Work outside the folder (another repo, your home folder) raises nothing: the character doing it wears an "elsewhere: " badge instead.
  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-one 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 runs on your machine; nothing is sent anywhere unless you post a change map to GitHub yourself. 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 hook strips each Claude Code event down to those paths, counts and flags before it sends anything, and sends only to a stage that answers with the id it registered (packages/cli/tests/script.test.ts plants secrets in every hook field and asserts none are sent).

ReadRenderedLeaves the machine
File pathsyesrepo-relativenever
File contentscounted only (±lines)only a file's diff, when you open it in the Changes view (read from your disk)never
Your promptstail never read; never storednonever
The agent's closing messagelast paragraph, truncated to 240 chars (turn_end.note)yes — shown with "your turn" so you know what it askednever
Command textfirst word + classified intent + redirect / delete targetsnonever
End-of-turn summaryfile paths and line counts of the turnshown by Claude Code under the replynever
PR comment (changes --pr)paths and line countsposted only when you confirm, with your own gh loginto GitHub, by you
Test outputsummary counts onlypass/failnever
Telemetry——none, ever
Audio—synthesized, no filesnever

The server binds to 127.0.0.1 only. Hooks always exit 0, never block your agent, and give up within about half a second.

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: Ship at Midnight Discord, one server for every tool, with a channel for Agent Theatre.

Site

agenttheatre.dev — the story, a playable Episode 1, all twenty-one 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.

Independent project, not affiliated with or endorsed by Anthropic, Microsoft, Anysphere (Cursor), Codeium (Windsurf), OpenAI or Google. Claude and Claude Code are trademarks of Anthropic; other names belong to their owners.


Agent Theatre is a free, non-commercial passion project. MIT licensed; bundled third-party code is listed in THIRD_PARTY_LICENSES.txt. It runs locally and sends no telemetry (privacy).

Reviews

No reviews yet

Be the first to review this server!