debugbrief

debugbrief command [arguments]

debugbrief records what you do while debugging and turns it into an evidence-backed Markdown report suitable for a pull request, a handoff, or an incident note. Unlike AI summarizers, the report is built only from recorded evidence: the commands you ran, their output, the files that changed, and the notes you added.A typical workflow is init once per project, then start to open a session, run to execute and capture commands, note to jot observations, and end to produce the report. The generated document includes a summary of test results and file changes, a red-to-green analysis with timing, a command timeline, error observations, and attempted fixes. Reports can be rendered in pr, handoff, or incident styles.debugbrief is a Python tool, typically installed with pipx install debugbrief (also available via uv tool install debugbrief or pip install debugbrief).

init

Configure the project and display the workflow.

Begin a new debugging session with the given title.

Record an observation in the active session.

Execute a command and capture its output as evidence.

Re-execute the most recently captured command.

Generate and save the report, then close the session.

Show details of the active session.

Display the report without closing the session.

Abandon the active session.

Validate project health and optionally repair it.

Fix a broken session pointer.

Locate the most recent report.

Display the most recent report.

Enumerate recorded sessions.

Display a specific recorded session.

The report reflects only what was captured through debugbrief; commands run outside debugbrief run are not included as evidence. Because output is stored verbatim, review reports for secrets or sensitive data before sharing them.

script(1), asciinema(1), git(1)

Source code