Replay your coding agent sessions as a map and a timeline
Python agent-observabilityai-agentsclaudeclaude-codecodexcoding-agentscursordeveloper-toolsdevtoolsgithub-copilotkirollmobservabilityopencodeprivacypythonsession-replaytypescriptvisualization
docs: make the README friendlier for contributors and discovery
adityajha2005222f457f335f
diff --git a/.github/ISSUE_TEMPLATE/agent_request.yml b/.github/ISSUE_TEMPLATE/agent_request.ymlnew file mode 100644index 0000000..9a284d6--- /dev/null+++ b/.github/ISSUE_TEMPLATE/agent_request.yml@@ -0,0 +1,23 @@+name: Support a new agent+description: Ask for (or offer to write) a parser for another coding agent.+labels: [enhancement]+body:+ - type: input+ id: agent+ attributes:+ label: Agent+ placeholder: Gemini CLI, Amp, Cline, Roo, Windsurf, Aider, ...+ validations:+ required: true+ - type: textarea+ id: where+ attributes:+ label: Where it stores sessions+ description: The folder or database, on which OS, and its format (JSONL, SQLite, ...) if you know it.+ - type: checkboxes+ id: help+ attributes:+ label: Can you help?+ options:+ - label: I can write the parser (see CONTRIBUTING.md, "Adding an agent")+ - label: I can provide a small redacted fixture transcriptdiff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlnew file mode 100644index 0000000..33c2eb3--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -0,0 +1,33 @@+name: Bug report+description: Something broke, a session didn't parse, or the viewer shows something wrong.+labels: [bug]+body:+ - type: textarea+ id: what+ attributes:+ label: What happened+ description: What you did, what you expected, and what you saw instead.+ validations:+ required: true+ - type: input+ id: agent+ attributes:+ label: Agent and version+ placeholder: Claude Code 2.1.0, Codex 0.50, Cursor 2.0, ...+ - type: input+ id: env+ attributes:+ label: agentplay version, OS and Python+ description: "`agentplay --version`, then your OS and `python --version`."+ validations:+ required: true+ - type: textarea+ id: output+ attributes:+ label: Terminal output+ description: Output of the command that failed. Check it for anything private before posting.+ render: text+ - type: markdown+ attributes:+ value: |+ **Never paste a raw transcript.** If a session doesn't parse, a small fixture with personal content removed is the most useful thing you can attach.diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000..2d24887--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,5 @@+blank_issues_enabled: true+contact_links:+ - name: Security issue+ url: https://github.com/Entelligence-AI/agentplay/security/policy+ about: Please report security issues privately, not as a public issue.diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdnew file mode 100644index 0000000..a6bc110--- /dev/null+++ b/.github/pull_request_template.md@@ -0,0 +1,11 @@+## What and why++<!-- One change per PR. Link the issue it closes, if any. -->++## Checklist++- [ ] `make check` passes+- [ ] Tests added or updated+- [ ] No prompt text, model output, tool input/output, file contents or command arguments can reach a map, a log line or the viewer ([redaction contract](https://github.com/Entelligence-AI/agentplay/blob/main/docs/format.md#redaction-contract))+- [ ] No new network calls or Python runtime dependencies+- [ ] UI changes: before/after screenshots in light and dark (`pnpm screenshots` in `viewer/`)diff --git a/README.md b/README.mdindex 26789c4..8528c9f 100644--- a/README.md+++ b/README.md@@ -1,5 +1,14 @@# agentplay+<p>+ <a href="https://pypi.org/project/agentplay/"><img alt="PyPI" src="https://img.shields.io/pypi/v/agentplay"></a>+ <a href="https://pypi.org/project/agentplay/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/agentplay"></a>+ <a href="https://pepy.tech/project/agentplay"><img alt="Downloads" src="https://static.pepy.tech/badge/agentplay/month"></a>+ <a href="https://github.com/Entelligence-AI/agentplay/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Entelligence-AI/agentplay/actions/workflows/ci.yml/badge.svg"></a>+ <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-blue"></a>+ <a href="https://github.com/Entelligence-AI/agentplay/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Entelligence-AI/agentplay?style=social"></a>+</p>+**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.**```bash@@ -12,6 +21,8 @@ That one command finds the agent sessions already on your machine, builds a reda<sub>Screenshot of the bundled demo session (synthetic data). Dark mode: [docs/images/explorer-dark.png](docs/images/explorer-dark.png).</sub>+If agentplay shows you something about your agent you didn't know, a ⭐ helps other people find it.+---## Contents@@ -289,13 +300,33 @@ Test suites:## Contributing-Contributions are very welcome. The most valuable ones are:+Contributions are very welcome, and you don't need to know the whole codebase to make one. The most valuable are:++1. **A parser for another agent**: Gemini CLI, Amp, Cline, Roo, Windsurf or Aider. Each is one file plus a few registration lines; [CONTRIBUTING.md](CONTRIBUTING.md#adding-an-agent) walks through it step by step, and [`codex.py`](python/src/agentplay/_core/ingestion/coding_agent/_sources/local/parsers/codex.py) is a good one to copy.+2. **Fixture transcripts** for an agent version that broke parsing, with personal content removed. Open a [parser bug](https://github.com/Entelligence-AI/agentplay/issues/new?template=bug_report.yml) and attach one.+3. **Viewer improvements** that make a session easier to read. The viewer runs on demo data with `pnpm dev` in `viewer/`, no sessions needed.+4. **Docs and install fixes**, especially for Windows and WSL.++Getting started:++```bash+git clone https://github.com/Entelligence-AI/agentplay && cd agentplay+make setup && make check # everything CI runs, locally+```++- Looking for somewhere to start? Try a [good first issue](https://github.com/Entelligence-AI/agentplay/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or one marked [help wanted](https://github.com/Entelligence-AI/agentplay/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).+- Want an agent supported but can't write the parser? [Request it](https://github.com/Entelligence-AI/agentplay/issues/new?template=agent_request.yml) and say where it stores sessions.+- For a new feature, open an issue first so we can agree it fits.++[CONTRIBUTING.md](CONTRIBUTING.md) has the privacy rules every change must keep and how to run the suites. Report security issues privately; see [SECURITY.md](SECURITY.md).++### Contributors++<a href="https://github.com/Entelligence-AI/agentplay/graphs/contributors"><img alt="Contributors" src="https://contrib.rocks/image?repo=Entelligence-AI/agentplay"></a>-1. **A parser for another agent**: Gemini CLI, Amp, Cline, Roo, Windsurf or Aider.-2. **Viewer improvements** that make a session easier to read.-3. **Fixture transcripts** for an agent version that broke parsing, with personal content removed.+### Star history-[CONTRIBUTING.md](CONTRIBUTING.md) walks through each of these, the privacy rules every change must keep, and how to run the suites. Report security issues privately; see [SECURITY.md](SECURITY.md).+<a href="https://star-history.com/#Entelligence-AI/agentplay&Date"><img alt="Star history chart" src="https://api.star-history.com/svg?repos=Entelligence-AI/agentplay&type=Date" width="600"></a>## Known limitationsdiff --git a/python/pyproject.toml b/python/pyproject.tomlindex cdd913a..f645d63 100644--- a/python/pyproject.toml+++ b/python/pyproject.toml@@ -11,7 +11,7 @@ license = "Apache-2.0"license-files = ["LICENSE", "NOTICE", "THIRD_PARTY_NOTICES.md"]requires-python = ">=3.11"authors = [{ name = "Entelligence AI" }]-keywords = ["claude-code", "codex", "cursor", "copilot", "coding-agent", "observability", "developer-tools"]+keywords = ["claude-code", "codex", "cursor", "copilot", "github-copilot", "opencode", "kiro", "coding-agent", "ai-agents", "llm", "session-replay", "agent-observability", "observability", "developer-tools"]classifiers = ["Development Status :: 3 - Alpha","Environment :: Console",@@ -28,6 +28,7 @@ dependencies = [][project.urls]Homepage = "https://github.com/Entelligence-AI/agentplay"+Documentation = "https://github.com/Entelligence-AI/agentplay#readme"Issues = "https://github.com/Entelligence-AI/agentplay/issues"Source = "https://github.com/Entelligence-AI/agentplay"Security = "https://github.com/Entelligence-AI/agentplay/security/policy"