Skip to content
MCP server

Agent Theatre

Replay a Claude Code session as an animated scene, with a map of every file changed

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, vscode, Web
Runs
Locally
Version
1.9.0
Listing updated
3 days ago

About Agent Theatre

Agent Theatre is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Agent Theatre treats your repository as a stage: folders become districts, files become buildings and test files become beacons. The coding agent is a character, chosen from a cast of twelve, that walks to the files it reads, builds on the ones it edits and runs tests at the beacons. Subagents arrive at a dock as other cast members. You can watch live or replay past sessions.

It checks claims against evidence: if the agent says it is done and no test has passed since the last edit, a gremlin hides behind it, and when tests do pass a count chip appears. Twenty-one stages such as Island, Harbour, Observatory and Moonbase are suggested based on what the repo looks like, with synthesised sound and six bundled synthetic episodes.

The Changes view maps every file the agent touched by folder, sized by lines changed and coloured new, edited, deleted or read. It is confirmed against git so shell edits and mid-session commits count, and edits by you or a formatter are marked as not by the agent. After each turn Claude Code shows a one-line summary, and npx agent-theatre changes can print Markdown or JSON or post the map as a pull request comment after asking you. A VS Code extension lists agent changes in the Explorer. It is open source and runs on your machine, and the Changes feature stores paths and line counts only.

Install

Run in a terminal

claude mcp add agent-theatre -- npx -y agent-theatre

Add to claude_desktop_config.json

{
  "mcpServers": {
    "agent-theatre": {
      "command": "npx",
      "args": [
        "-y",
        "agent-theatre"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "agent-theatre": {
      "command": "npx",
      "args": [
        "-y",
        "agent-theatre"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "agent-theatre": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "agent-theatre"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

What it does

Repo as a stage
Maps folders, files and tests to districts, buildings and beacons with live or replayed sessions.
Claim checking
Shows a gremlin when the agent says it is done without a passing test, and a count chip when tests pass.
Changes map
Shows every touched file sized by lines changed, confirmed against git.
Pull request comment
Posts the change map as one comment with your own gh login after you approve.
VS Code integration
Lists agent changes in the Explorer and opens the editor diff on click.
Twenty-one stages
Suggests visual stages to match your repo type, each with its own sound.

Good for

  • Review what a long agent session changed before committing
  • Tell the agent's edits apart from your own or a formatter's
  • Hand reviewers a summary of an agent's pull request
  • Replay a past Claude Code session to understand what happened
  • Spot an agent claiming success without passing tests

Pricing

Open source

Open source and runs locally

Prices change. Check agenttheatre.dev before you buy.

Agent Theatre FAQ

Does it send my code anywhere?

The site says it runs on your machine, and the Changes view uses paths and line counts only; a file's diff is read from disk only when you open it.

How do I get a change map for a pull request?

Run npx agent-theatre changes --pr, which posts or updates one comment using your gh login after asking.

Can I turn off the per-turn summary?

Yes. Set AGENT_THEATRE_SUMMARY=0.

Is it only for Claude Code?

The README describes turning a Claude Code session into the scene, using hooks for live view and replay of real sessions.

Can I try it without my own repo?

Yes. Six synthetic episodes can be watched at agenttheatre.dev.

Is Agent Theatre free?

Yes. Agent Theatre is open source, so you can use and self-host it for free.

How do I add Agent Theatre to Claude Code?

Run this command in your terminal: claude mcp add agent-theatre -- npx -y agent-theatre

What are the best alternatives to Agent Theatre?

The closest alternatives to Agent Theatre are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to Agent Theatre

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools