agentplay

See what your coding agent actually did. Replay every session as a map and a timeline: what it read, what it edited, what failed, and what it shipped. Local, open source, works across Claude Code, Codex, Cursor, Copilot, OpenCode and Kiro.

uvx agentplay

That one command finds the agent sessions already on your machine, builds a redacted replay of each one, and opens a local viewer. No account and no API key are required, and your session data never leaves your machine. The only network call is an optional email signup in the viewer, described under Privacy; set AGENTPLAY_NO_NETWORK=1 to switch it off.

Screenshot of the bundled demo session (synthetic data). Dark mode: docs/images/explorer-dark.png.

Contents

• Why this exists
• Install
• Using the viewer
• Supported agents
• Privacy
• Command reference
• The session map format
• How it works
• Configuration
• Development
• Contributing
• Known limitations
• License and credits

Why this exists

Your agent's transcripts already record what it did: which files it read before editing, which commands it retried, which MCP servers failed, where the context window filled up, and which subagents came back empty. That data sits in ~/.claude, ~/.codex, ~/.cursor and similar folders, and almost nobody looks at it.

agentplay makes that data readable. Every session becomes a map of everything it touched and a timeline you can play back, so you can answer questions like:

• What did the agent read before it edited this file, and what did it never open?
• Which commands failed, and how many times did it retry the same one?
• Where did the context window fill up, and what did the subagents bring back?
• Which PRs, commits and tickets did the session produce?

Install

You need Python 3.11 or newer. agentplay has no runtime dependencies beyond the standard library.

uvx agentplay                 # run without installing (uv: https://docs.astral.sh/uv/)
pipx run agentplay            # same, with pipx
pip install agentplay         # or install it into an environment

Setting up with a coding agent? Point it at install.md: step-by-step instructions written for an agent, covering every option above and how to check the viewer is up.

git clone https://github.com/Entelligence-AI/agentplay
cd agentplay
make setup        # python venv + viewer node_modules
make viewer       # build the web viewer and copy it into the Python package
make run          # agentplay view, from the checkout

The default session folders (C:\Users\<you>\.claude, .codex, and so on) are found automatically; no path configuration is needed.

make works under Git Bash or MSYS2 (it uses python\.venv\Scripts\python.exe on Windows) and in WSL. Without make, run the equivalent steps in PowerShell:

git clone https://github.com/Entelligence-AI/agentplay
cd agentplay
uv venv python\.venv
uv pip install --python python\.venv\Scripts\python.exe -e "python[dev]" jsonschema
cd viewer
corepack pnpm install --frozen-lockfile
corepack pnpm run build
Remove-Item -Recurse -Force ..\python\src\agentplay\viewer -ErrorAction SilentlyContinue
Copy-Item -Recurse dist ..\python\src\agentplay\viewer
cd ..\python
.venv\Scripts\agentplay view

The viewer needs the pnpm version pinned in viewer/package.json (10.x). An older pnpm, such as 8, rejects the lockfile. corepack pnpm ... (as above) runs the pinned version without changing your global pnpm.

To try the viewer on its own, run pnpm dev in viewer/; it loads three synthetic demo sessions. You can also drag any agentplay/v1 file onto the page.

Using the viewer

agentplay            # same as `agentplay view`

Found 412 sessions  claude-code 301 · codex 88 · cursor 23
Built 412 new, 0 unchanged, 0 skipped in 9.4s. Nothing left this machine.
Viewer → http://127.0.0.1:7317/   (Ctrl+C to stop)

Illustrative counts. Builds are incremental, so later runs only rebuild sessions whose transcript changed.

In the viewer:

• The map is a radial tree of everything the session touched: repos, directories and files (seen, read or edited), shell verbs, MCP servers and tools, skills, subagents, web hosts, error classes, models, and the outputs it produced (commits, PRs, tickets).
• The timeline plays the session back at 1x, 4x or 16x. Scrub it, or switch between step axis and wall-clock time. Its lanes show prompts, errors, delays, outputs, edits, exploration, MCP, skills, tools, model, cost, tokens, subagents and context size, with compactions marked.
• Keyboard: Space plays and pauses. Arrow keys step, Shift steps by 10. E, X, D, O and R jump to the next edit, error, delay, output or retry.
• Scopes: pick a task, a model, or a single subagent ("agent lens"). The whole explorer re-scopes to it.
• Tasks: a session is split into tasks, usually one per prompt you gave it, each labelled with the start of that prompt. Labels live only in your local index, are added when the viewer loads a session, and are never written into a map (see Privacy).
• Errors: the Errors tab lists every error in the session, grouped by class and ranked by the longest run of the same failing command. Click a row to seek the replay to it. The error, PR and subagent badges on the session header narrow the timeline the same way.

Every view is a URL, so a link to a moment in a session reopens it for anyone who runs the viewer on the same data.

Supported agents

"Main lane only" means the session's own tool calls are all there, but subagent work is not split out into separate lanes on the map.

Run agentplay agents to see which of these were found on your machine. Every location can be overridden (see Configuration). A parser for another agent is the most useful contribution you can make; see CONTRIBUTING.md.

Privacy

agentplay was designed so that you can show a map to someone else without worrying about what is in it.

Your session data never leaves your machine. There is no usage telemetry, no update check and no upload of sessions or maps. The viewer is served from 127.0.0.1 and loads no remote fonts or scripts. It shows a few links to Entelligence (a banner, the welcome card, sample-review and "fix now" blocks); they open only when you click them, carry only a tag naming where you clicked (?src=agentplay-viewer&from=banner) and nothing from your sessions, and the viewer fetches nothing from them on its own. Cursor's billed-usage lookup, which would call Cursor's API with your stored token, is deliberately disabled.

The one network call is your email, if you give it. The first time the viewer opens, it offers to take your email so Entelligence can tell you about new features. If you type one in, agentplay sends Entelligence the event (signup, or later disconnect), that email, a random install id (generated once and kept in ~/.agentplay/account.json, so it ties your signup and disconnect to the same install), its version number and the time, and nothing else: no session data, paths or repo names. "Continue without email" sends nothing. All of it is in one file, account.py; grep -rn urllib.request python/src/ finds it and nothing else. You can disconnect from the top bar, which forgets the email locally and sends Entelligence one request to delete it; it is sent once and not retried, so if Entelligence can't be reached at that moment it may not arrive, and the email may stay on the list. DO_NOT_TRACK=1 or AGENTPLAY_NO_NETWORK=1 turns the offer off and blocks the request. Details: docs/signup-endpoint.md.

A map document never contains:

• prompt text, assistant text, or reasoning;
• tool inputs or outputs, or file contents;
• command arguments. A shell command is recorded as its verb only (git log, pytest), never git log --author=...;
• subagent prompts or descriptions. Only their type and model are recorded;
• user message text. Only its length and counts of images and links are recorded.

A map does contain: repo names and remotes, repo-relative fil