Developer tool

DebugBrief

A debugging session becomes a clean engineering handoff.

DebugBrief records commands, exit codes, timestamps, and repository changes, then turns that event history into a pull-request, handoff, incident, or JSON report.

Try demo View repository PyPI Recorded demo

My role: Independent project · product, CLI, capture runtime, and release pipeline
Status: Installable as debugbrief, with Linux and macOS release checks.
Stack: Python · Typer · Rich · Pydantic · PyPI

The problem

Debugging handoffs lose the useful details.

Debugging handoffs are usually written after the fact, so commands, exit codes, timing, and file changes get lost.

What I built

A CLI that captures the session as it happens.

I built a CLI that runs commands in a pseudo-terminal, tracks Git changes, detects fail-to-pass test runs, and exports PR, incident, handoff, and JSON reports.

How it works

The main path.

01
Start a session and snapshot the repository state.
02
Run a command through the capture wrapper while streaming its output.
03
Persist the command, directory, exit code, duration, bounded preview, and Git delta.
04
Match failed and passing executions of the same recognized check.
05
Render a PR, handoff, incident, or JSON report from recorded events only.

Key engineering decisions

Three decisions that matter.

Reports derive from events

The report model is built from command results and repository snapshots instead of a retrospective story typed after the fact.

src/debugbrief/derive.py · src/debugbrief/models.py

Capture without hiding the terminal

Commands run under a pseudo-terminal with live streaming, timeout handling, bounded storage, and process-group cleanup.

src/debugbrief/command_runner.py

One record, several handoffs

PR, handoff, incident, and JSON reports all come from the same recorded session.

src/debugbrief/reporters/

Results

Selected outcomes.

Benchmarks, packages, and checks from the project.

PyPI

published package

DebugBrief is publicly installable as debugbrief.

Python Package Index ↗

1 → 0

recorded check transition

The committed sample captures the same pytest command failing and then passing, alongside the changed file.

examples/sample-pr.md ↗

2 OS

release matrix

The project checks supported Python versions on Linux and macOS and validates the built package before release.

GitHub Actions ↗

Interactive demo

Try the main path.

Record a failing test, apply the edit, rerun it, and generate a PR brief.

Session timeline

0 / 6 events

Start the session to capture the first event.

PR brief

waiting

The brief is generated only after the rerun and Git change are recorded.

Watch the terminal recording

Scope

Current constraints.

Capture is explicit through debugbrief run rather than a full terminal transcript.
Output storage is bounded, and full-screen terminal interfaces sit outside the capture model.
Supported runtimes are Unix-like; redaction is best effort.