Agent Debrief
Understand what your AI coding agent actually built.
AI coding agents finish tasks faster than you can read the diff. Agent Debrief connects to your agent, records what it did, analyses the resulting code, and explains it five ways — every explanation tied to evidence, and every claim labelled as verified, agent-reported, inferred or unverified.
| Experience | What you get | |
|---|---|---|
| 1 | Quick Summary | The completed task in ~30 seconds: ≤5 bullets, files, tests, risks, remaining work |
| 2 | Visual Flow | The application flow (entry → handler → logic → data → response) and the agent's own execution flow |
| 3 | Teach Me | The technical concepts the code uses, one at a time, at beginner / developer / advanced level |
| 4 | Talk to Me | A spoken explanation you can interrupt, continue and question (optional, browser speech) |
| 5 | Ask Questions | Evidence-backed answers: direct answer → code references → flow → limitations |
Screenshots show the built-in simulated demo session (agent-debrief demo), not a real agent run.
Status
v0.1.0 — Claude Code + Python. Local-first, no account, no external database.
| Area | State |
|---|---|
| Claude Code integration (hooks + transcript) | Implemented. Verified against simulated hook payloads and transcripts; please test it on your machine and report problems (see Known limitations). |
| Python analysis (AST, calls, routes, architecture) | Implemented and tested |
| Codex, Cursor | Not supported. Documented placeholders only. |
| Other languages | Not yet (changed non-Python files are listed, not analysed) |
| AI explanations | Optional. Works fully offline with template-based explanations; add an API key for AI-written ones |
Install
Requires Python 3.11+ and git. Node.js is not needed to use the tool.
# recommended
uv tool install agent-debrief # or: pipx install agent-debrief
agent-debrief init
agent-debrief connect claude # asks before touching ~/.claude/settings.json
agent-debrief serve # opens http://127.0.0.1:8765
debrief is a short alias for agent-debrief. For installing from a source checkout and for Windows, macOS and
Linux details, see docs/installation.md.
Want to look around first? agent-debrief demo creates a throw-away project and replays a simulated
Claude Code session so you can explore every tab without running an agent.
How it works
Claude Code ──hooks──▶ event pipeline ──▶ SQLite ──▶ analysis worker ──▶ task understanding ──▶ 5 experiences
(redact, normalize, (git baseline diff, (one common, (local web UI)
correlate, dedupe) AST, relationships, evidence-linked
evidence, risks) model)
- Hooks (
SessionStart,UserPromptSubmit,PreToolUse,PostToolUse,Stop,SessionEnd) call a tiny command that stores each event — secrets redacted — straight into a local SQLite file. The hook never prints, never blocks and always exits 0. - When the prompt is submitted, a baseline of your git working tree is snapshotted. After the agent stops, only changes since that baseline are attributed to the task — a dirty tree is never blamed on the agent.
- The understanding engine parses changed Python (AST), resolves calls, classifies architecture layers, parses test output, flags risky patterns and attaches an evidence record to every fact.
- The communication engine turns that one model into the five experiences. With an AI provider configured, an LLM rewrites the wording — but it can only cite real evidence, cannot add flow edges, and any claim naming something that is not in the evidence is downgraded to unverified.
Details: docs/architecture.md · docs/event-contracts.md · docs/api-specification.md · docs/security.md
Trust model
Every statement carries one of four labels:
| Label | Meaning |
|---|---|
| Verified | Observed directly: a git diff, an AST fact, a recorded tool call, parsed test output |
| Agent reported | The agent said so; not independently checked |
| Inferred | An LLM/heuristic interpretation that cites real evidence — never presented as fact |
| Unverified | No usable evidence — a hypothesis |
"Completed" always means the agent stopped; Agent Debrief never re-runs your tests or your code.
Privacy
Local-first. Nothing leaves your machine unless you configure an AI provider, and then only the redacted
context shown by AI context on every task (you can turn off sending code and prompts separately). Hook
installation is explicit and reversible (agent-debrief disconnect), and you can delete a session or all data
from the UI or the CLI. See docs/security.md.
Commands
| Command | |
|---|---|
agent-debrief init |
Create the data directory, config and database |
agent-debrief connect claude |
Install the Claude Code hooks (backs up your settings first) |
agent-debrief status |
Integrations, captured data, AI provider |
agent-debrief sessions |
List captured tasks (--available lists importable Claude transcripts) |
agent-debrief import |
Import past Claude Code sessions from transcripts |
agent-debrief analyze <task> |
Analyse a task from the terminal (latest works) |
agent-debrief serve |
Start the web interface (loopback only) |
agent-debrief doctor |
Diagnose configuration, including a real hook self-test |
agent-debrief disconnect / uninstall |
Remove the hooks (--purge-data removes everything) |
agent-debrief demo |
Explore with a simulated session |
Known limitations
- Real Claude Code runs are not part of the automated tests. The hook and transcript code follows the
documented formats and is tested with realistic simulated payloads; the transcript format is not a stable public
contract.
agent-debrief doctorand the log at<data dir>/logs/hook.loghelp diagnose mismatches. - Hooks start a short Python process on state-changing tool calls and on every completed tool call
(typically tens of milliseconds each).
doctorprints the measured time. - Static analysis is Python-only. Calls through unknown objects are not resolved (no edge is drawn) rather than guessed.
- "Why did the agent do X?" can only be answered when the agent said why; events record what, not why.
- Speech uses your browser's Web Speech API (quality and availability vary; Chrome/Edge/Safari). It is optional.
- Codex and Cursor adapters are planned (release 0.6).
Development
git clone https://github.com/kishore600/agent-debrief.git && cd agent-debrief
uv sync
npm install && npm run build:web # builds the UI into the Python package
uv run agent-debrief init && uv run agent-debrief serve
uv run pytest # backend tests
npm run typecheck && npm run test:web
See CONTRIBUTING.md and docs/development.md.
License
MIT — see LICENSE.
Metadata
Release files for agent-debrief 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_debrief-0.1.0.tar.gz | 521.2 kB | Without provenance | Details for agent_debrief-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_debrief-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_debrief-0.1.0-py3-none-any.whl |
Total release size: 884.6 kB
Release files / agent_debrief-0.1.0.tar.gz
| Download URL | agent_debrief-0.1.0.tar.gz |
|---|---|
| Size | 521.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
399a6e76ab5559303bc6f15a1ff1a1a197d7d114c2839d1814d245b5d771489d
|
|
BLAKE2b-256 checksum How to use checksums |
9b2193e0ab3c24c0d94a5afcb25b845b598b7ce65229ba848c54cae30247a907
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / agent_debrief-0.1.0-py3-none-any.whl
| Download URL | agent_debrief-0.1.0-py3-none-any.whl |
|---|---|
| Size | 363.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
90606352301c33e7f3b720213bbd69387a32d005348227f04133ec9fcb77e85d
|
|
BLAKE2b-256 checksum How to use checksums |
a9295559155622fe87c53ae2335d750459302165e24a50475b6e9a0b9f10981e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for agent-debrief 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.