Replay your coding agent sessions as a map and a timeline
Contributing to agentplay
Thanks for helping. This page covers the most useful kinds of contribution, the rules every change has to keep, and how to run everything locally.
Before you build a feature
agentplay is maintained by Entelligence on a product roadmap. Parsers for new agents, bug fixes and documentation are always welcome as pull requests. For a new feature, please open an issue first so we can agree it fits before you spend time on it; we may decline a good feature that doesn't.
Ground rules
- Privacy is the product. A change must never cause a map, a log line, or the viewer to contain prompt text, model output, tool input or output, file contents, or command arguments. The full rules are in docs/format.md. If you are not sure, ask in the PR.
- No new network calls. The only one is the opt-in email signup in
account.py, and the README promises that. Session data never goes over the network, and a feature that needs the network does not belong in the core tool.tests/test_account.pyfails ifurllib.requestappears in any other file. - No runtime dependencies for the Python package. It runs on the standard library so that
uvx agentplaystarts instantly and installs cleanly everywhere. Dev and test dependencies are fine. - Keep internal references out.
make checkrunsscripts/check_clean.py, which rejects ticket ids, private links and credential shapes.
Setup
make setup # python/.venv (pytest, ruff, jsonschema) + viewer/node_modules
make test # everything
make check # lint + typecheck + tests + hygiene guard, what CI runs
On Windows, make works under Git Bash or MSYS2, or in WSL. Without make, follow the PowerShell steps under "Windows" in the README. To run the Python tests directly:
cd python
.venv\Scripts\python -m pytest -q
Python code lives in python/src/agentplay, and its tests are in python/tests, with parser tests in python/tests/core. The viewer lives in viewer/; see viewer/README.md.
Adding an agent
A parser turns one agent's transcript into the shared span shape: a root Session span, one Turn span per turn, and one tool span per tool call. Everything downstream (the builder, the viewer) then works without further changes.
- Get real transcripts. Use two or three real sessions from the agent, and include one with a failed tool call if you can. Strip any personal content before committing them as fixtures. Keep them small.
- Write the parser as
python/src/agentplay/_core/ingestion/coding_agent/_sources/local/parsers/<agent>.py, exposingparse_<agent>(data, trace_id, user_id=None, project_name=None) -> (TraceData, list[SpanData]).codex.pyis a good one to copy. Map the agent's tool names onto the canonical taxonomy intool_taxonomy.pyso that reads, edits and shell calls are classified correctly. - Register it:
- add a value to
AgentTypeand a sniffing rule todetect_agentinparsers/base.py; - export it from
parsers/__init__.py; - add an indexer for the agent's home layout in
_sources/local/source.py.
- add a value to
- If the agent stores sessions in a database rather than files, add a decoder to
materialize.pythat writes one NDJSON transcript per session into the cache, following the OpenCode one. Open databases read-only (mode=ro&immutable=1), or copy them first if they are WAL-mode and may be live. - Tell discovery where it lives. Add the default home, and a
AGENTPLAY_<AGENT>_HOMESoverride, toHomesindiscover.py. Add the agent toAGENTS, and to the tables in the README. - Test it. Add parser tests in
python/tests/core/. Also add one test that builds a map from your fixture and asserts that no text from it appears in the map (seetest_builder_never_leaks_free_text).
Changing the format
agentplay/v1 only grows:
- add fields, never rename or repurpose one;
- update docs/format.md, schema/agentplay-v1.schema.json and the viewer's zod schema (
viewer/src/core/schema.ts) in the same PR; - keep new fields optional for readers, since older maps will not have them.
Using AI tools
AI coding tools are welcome. You stay responsible for everything you submit.
- A human must be in the loop. Agents may open pull requests, but a person must have reviewed the diff, understand every line and answer review questions. We close pull requests with no one behind them.
- The description must be true and clear. You or your agent can write it. Either way, it says what changed and why, matches the diff, and stays short: no filler, no restating the code.
- Never claim a check you did not run. The test plan says what you actually ran and saw, and what you did not test.
Pull requests
- Keep each PR to one change, and include tests that fail without it.
- Run
make checkbefore pushing. - Fill in the PR template: a short summary of what changed and why, the linked issue, and a test plan.
- For UI changes, attach before and after screenshots in light and dark (
pnpm screenshotsinviewer/). - By contributing, you agree that your contribution is licensed under the Apache License 2.0.
Releasing
Maintainers: see docs/RELEASING.md for the release steps.
Code of conduct
Participation in this project is governed by the Code of Conduct.