Metadata-Version: 2.5
Name: agent-debrief
Version: 0.1.0
Summary: Understand what your AI coding agent actually built — summaries, flows, lessons, voice and Q&A, all backed by evidence.
Project-URL: Homepage, https://github.com/kishore600/agent-debrief
Project-URL: Repository, https://github.com/kishore600/agent-debrief
Project-URL: Issues, https://github.com/kishore600/agent-debrief/issues
Project-URL: Documentation, https://github.com/kishore600/agent-debrief/tree/main/docs
Author: Agent Debrief contributors
License: MIT
License-File: LICENSE
Keywords: ai,claude-code,code-understanding,coding-agent,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# 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 |

![Dashboard](docs/images/dashboard.jpg)
![Summary](docs/images/summary.jpg)
![Visual flow](docs/images/visual-flow.jpg)

*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](#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.

```bash
# 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](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/architecture.md) · [docs/event-contracts.md](docs/event-contracts.md) ·
[docs/api-specification.md](docs/api-specification.md) · [docs/security.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](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

```bash
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](CONTRIBUTING.md) and [docs/development.md](docs/development.md).

## License

MIT — see [LICENSE](LICENSE).
