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, Kiro, Gemini CLI, Antigravity CLI, Command Code and Goose.
uvx agentplay@latest
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.
If agentplay shows you something about your agent you didn't know, a ⭐ helps other people find it.
Contents
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@latest # run the newest release 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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
