Skip to main content

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

Overview Quick Summary Visual Flow Teach Me

Screenshots show the built-in simulated demo session (agent-debrief demo), not a real agent run.

Status

v0.1.1 — 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)
  1. 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.
  2. 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.
  3. 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.
  4. 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 · docs/design-system.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 doctor and the log at <data dir>/logs/hook.log help diagnose mismatches.
  • Hooks start a short Python process on state-changing tool calls and on every completed tool call (typically tens of milliseconds each). doctor prints 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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-debrief 0.1.1
File Size Uploaded Provenance Actions
agent_debrief-0.1.1.tar.gz 709.7 kB Without provenance Details for agent_debrief-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-debrief 0.1.1
File Interpreter ABI Platform Actions
agent_debrief-0.1.1-py3-none-any.whl Python 3 none any Details for agent_debrief-0.1.1-py3-none-any.whl

Total release size: 1.2 MB

Release files / agent_debrief-0.1.1.tar.gz

Download URL agent_debrief-0.1.1.tar.gz
Size 709.7 kB
Tags Source
SHA-256 checksum
How to use checksums
d4d3372ba560130e835544c4665a70e07d9f347bf503ecb74acd7bc0f5cba2c1
BLAKE2b-256 checksum
How to use checksums
672f27a47c49976a028e4396ec7d174db527b5666eef66db7c0c720aece96737
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.1-py3-none-any.whl

Download URL agent_debrief-0.1.1-py3-none-any.whl
Size 467.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4bc264e6c8845e3dcf5ec7aedfeb2a936177f7819423b80b262ec31953ab264a
BLAKE2b-256 checksum
How to use checksums
45c061a66f0fa9ccfc4c12abb7d213e511a78019e40c374be9594b53ada6719e
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.1

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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page