Skip to content

Replay your coding agent sessions as a map and a timeline

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.yml
new file mode 100644
index 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 transcript
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 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.yml
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 limitations
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 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"