Skip to main content

DebugBrief

CI PyPI

Record what you do while debugging and turn it into an evidence-backed report for a pull request, a handoff, or an incident note.

A failing test streams live, the fix lands, redo passes, and the generated report appears

DebugBrief captures the notes you write and the commands you run, then builds a report from what actually happened: what you tried, what failed, what passed, and which files changed in between. It does not use AI and does not infer a root cause or report a test result you did not get.

The product site includes the workflow, command reference and a local JSON Evidence Explorer: open the site source, or run python3 scripts/serve_site.py for a local preview. The site uses CDN fonts and optional animation libraries; imported reports stay in the browser and are never uploaded. It is included in the source distribution and is intentionally repository/deployment content rather than runtime wheel data.

Install

pipx install debugbrief
# or
uv tool install debugbrief

These examples require DebugBrief 1.4.0 or newer. Upgrade an older install with pipx upgrade debugbrief or uv tool upgrade debugbrief. Plain pip install --upgrade debugbrief works too inside an environment. DebugBrief needs Python 3.9 or newer. Native Git is used when available to capture repository metadata and changed files. The project you debug does not need to be Python; only DebugBrief runs on Python.

Quickstart

debugbrief run -- pytest -q test_calc.py             # auto-starts a local session
# make the fix
debugbrief redo                                      # same test, now passes
debugbrief end --format html --open                 # review the proof in your browser

A session title and notes are optional; add them when the output tells you something worth keeping. Everything after -- runs exactly as you typed it, with its output streaming live to your terminal. DebugBrief flags (--timeout, --shell, --no-redact, --verify) go before the --. redo runs the last captured command again in its recorded directory using the current files and environment; use redo --dry-run to preview it without a lease or execution. Conservative destructive redos ask for confirmation, and --yes bypasses that prompt. end defaults to the pr report mode.

Tip: a one-line alias makes the capture prefix disappear in daily use.

alias db="debugbrief run --"
db pytest -q

What you get

A report built only from recorded evidence. A short excerpt from a real run:

## Summary

Failing check `python -m pytest -q test_calc.py` passed after 2 attempts over 2s, changes touched calc.py.

## Red to green

A check failed at 12:02:09 and `python -m pytest -q test_calc.py` passed at 12:02:10 (window 1s).

Between the failing and passing checks, these files changed (correlation, not proven cause):
- `calc.py`

Full samples: PR, handoff, incident.

How it works

  • run executes a command under a pseudo-terminal so its output streams live, then records the real exit code, a bounded output preview, the duration, and a per-command git snapshot when the project is a repository.
  • Pass or fail comes only from the exit code. A command counts as verified when a recognized test, build, lint, or typecheck runner exits 0, or when you explicitly declare another command with --verify and its exit status is trustworthy. Help, version and collection/list modes do not count, even with --verify. A prior failure is not required, but a currently failed or invalid check keeps the report unverified.
  • It works with any language. A recognized runner (pytest, jest, vitest, go test, cargo test, dotnet test, make check, and more) is classified automatically. Any other command is still captured, and you mark it a check with --verify.
  • end derives the report from those events: an explicit evidence state, the red-to-green window, the reproduce and verify commands, a timeline, the observed error, and the failed attempts. PR reports are compact by default; pass --detail full for the complete record. Empty sections are omitted.
  • end --format html writes a self-contained browser view; end --format all writes Markdown, JSON, and HTML together. Review it with debugbrief open --html, or use debugbrief last --open for a one-step handoff.
  • Generated reports show only the local repository basename by default; pass --include-full-path to end or preview when the absolute project root is intentional. Absolute paths in recorded commands, notes and output can still appear. Reports retain project-relative working directories; missing legacy directory data remains unknown.
  • Secrets are redacted before anything is written to disk. Redaction is best effort; --no-redact opts out for a single command.

Full command reference and the complete recognized-runner list: docs/COMMANDS.md. Security model and redaction details: SECURITY.md.

Post a report straight to a pull request (GitHub CLI optional):

debugbrief end --stdout | gh pr comment --body-file -

Commands

The six you use most:

Command What it does
start "<title>" Start a session
note <text> Record an observation
run -- <command> Run and capture a command
redo [--dry-run] [--yes] Re-run the last captured command, with a safe preview/confirmation gate
end [--mode pr|handoff|incident] [--format md|json|html|both|all] Finalize and write a report (default pr, Markdown)
open --html / last --open Review the saved proof in a browser or editor

The rest:

Command What it does
init Set up the project and show the workflow
status Show the active session
preview [--mode ...] [--format md|json|html] Print a report preview without ending the session
cancel [--yes] Abandon the active session; no report, local record retained
doctor [--fix] Health-check the project and state
recover Repair a broken session pointer after a crash
last Show the most recent report path
open Open the most recent report
list List recorded sessions
show <id> Show a recorded session

Full flags and behavior for each: docs/COMMANDS.md.

Dependencies

DebugBrief uses the Python standard library and native git. On Python 3.11 and newer it needs nothing else. On Python 3.9 and 3.10 it uses the small tomli package to read an optional .debugbrief.toml. DebugBrief itself makes no network requests, uses no AI, and collects no telemetry.

Supported platforms

Linux and macOS are tested in CI across Python 3.9 through 3.14. Other Unix-like systems may work but are not currently tested. Native Windows and PowerShell are not supported.

Limitations

  • Capture is explicit through debugbrief run. Output streams live while a bounded preview is stored for the report, so there is no full transcript.
  • Full-screen TUIs (a vim session, htop) are not meaningfully captured. Run those directly and record the outcome with note.
  • Redaction is conservative and best effort; it does not catch every secret.
  • Git sections need native git; outside a repository they are omitted.

Development

pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the full setup and contribution guidelines.

License

MIT. See LICENSE.

Metadata

Release files for debugbrief 1.4.0

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

Source distribution (sdist)

Source distribution for debugbrief 1.4.0
File Size Uploaded Provenance Actions
debugbrief-1.4.0.tar.gz 1.5 MB With provenance Details for debugbrief-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for debugbrief 1.4.0
File Interpreter ABI Platform Actions
debugbrief-1.4.0-py3-none-any.whl Python 3 none any Details for debugbrief-1.4.0-py3-none-any.whl

Total release size: 1.6 MB

Release files / debugbrief-1.4.0.tar.gz

Download URL debugbrief-1.4.0.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
4fcff31a83bbd8dd2761746fd104e4fe2ffa5894a9898f0b214f004c32da811f
BLAKE2b-256 checksum
How to use checksums
fefd24ac546ef03d52b0d618e15170fad5ab582ed3e76af2932675b64399d6b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Release files / debugbrief-1.4.0-py3-none-any.whl

Download URL debugbrief-1.4.0-py3-none-any.whl
Size 123.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a257e7db22261598cb79557187a2e08c5d9f3d581004d28fa667aeed49a9d6f8
BLAKE2b-256 checksum
How to use checksums
22985b1452c748488d4ba42e70053c84bb5a22a1290d33c874b6d2b973840144
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Security for debugbrief 1.4.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for debugbrief-1.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

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.

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