Documentation

For DebugBrief 1.4.0 and newer. Record a debugging session and export the report. Press / to find a section.

Quickstart

Starting a session is optional. The first run or note starts one automatically.

shell

$ pipx install debugbrief
$ debugbrief run -- pytest -q
# make the fix
$ debugbrief redo
$ debugbrief end --format html --open

note

Each run saves the command, exit code, duration, a bounded output preview and Git state when available.

Install

Python 3.9 or newer on Linux or macOS. The project you debug does not need to be Python. These examples require DebugBrief 1.4.0 or newer; check with debugbrief --version.

pipx install debugbriefrecommended for a standalone CLI

uv tool install debugbriefif you use uv tools

python -m pip install debugbriefinside an existing environment

Already installed? Run pipx upgrade debugbrief, uv tool upgrade debugbrief, or python -m pip install --upgrade debugbrief with the installer you used. PyPI 1.3.0 supports Markdown and JSON; HTML reports, browser-opening flags and the structured command history shown here require 1.4.0 or newer.

For a source checkout, run pipx install . from the directory containing pyproject.toml.

init, start and cancel

init creates the local directories, checks project health and suggests an optional alias. It does not start a session or write a report. start sets a title and records the initial Git state.

shell

$ debugbrief init
$ debugbrief start "Handle an expired cache entry"
# optional shortcut for captured commands
$ alias db="debugbrief run --"
$ db pytest -q

Setup adds .debugbrief/ to the local .git/info/exclude when available. It never changes the shared .gitignore.

cancel abandons the active session without writing a report. It asks for confirmation; --yes skips the prompt. The abandoned session stays on disk and still appears in list and show.

run

Put DebugBrief flags before --, then the command exactly as you would normally type it. Output streams live while the command, exit code, duration, output preview and Git snapshot are recorded. Commands execute from the directory where you invoke run, including project subdirectories; state stays at the project root.

shell

$ debugbrief run -- pytest -q

--timeout SECONDSstop a long-running command (default 300)

--verifydeclare a custom command as a check

--shellrun through the shell, for pipes and redirection

--no-redactstore raw output for this command

note

Record an observation without leaving the loop. Quoting is optional for plain prose.

shell

$ debugbrief note "the shared state is the suspect"
Noted locally · 1 note · session 3f8a1c2d

redo

Re-run the latest captured command in its original directory. This is a fresh execution using the current files, environment and dependencies, not a deterministic replay. Older sessions without a recorded directory use your current directory with a warning; a recorded directory that no longer exists is refused.

shell

$ debugbrief redo

note

--dry-run previews without executing. Destructive commands ask for confirmation; --yes bypasses it.

Checks and verification

Recognized test, build, lint and typecheck runners are classified automatically. A passing check needs a trustworthy zero exit code and a valid recorded timestamp. Evidence is verified when at least one eligible check passed and no check has a current failed or invalid result. A prior failure is not required. This verifies only the recorded checks, not the whole issue. Use --verify for a custom check.

Help, version, collection-only and test-listing invocations never count as verification, even with --verify. A red-to-green window needs the same command to fail and later pass in the same directory; changed-file correlation additionally needs Git evidence. A later failure keeps the report unverified even if a historical window exists.

pytest · vitest · jest · bun test · deno test · node --test · go test · cargo test · npm/pnpm/yarn test · npm run build · tsc --noEmit · ruff · make check · tox · unittest · dotnet test · ctest · phpunit · mix test · swift test · rspec · mvn test · gradle test

end

Finalize the session and write the report. PR reports are compact by default; --detail full includes the full record in Markdown. JSON and HTML always keep the complete evidence.

shell

$ debugbrief end --mode pr
$ debugbrief end --mode handoff
$ debugbrief end --mode incident

Report modes

prReproduce and verify commands, red to green window, changed files, failed attempts.

handoffCurrent status, your notes, timeline, next steps taken only from your notes.

incidentTime window, observed error, resolution, follow-up items.

Output formats

--format mdMarkdown brief (default)

--format jsonstructured evidence

--format bothMarkdown and JSON

--format htmlself-contained browser report

--format allMarkdown, JSON and HTML

Every report states whether it is verified or unverified and that the root cause was not inferred.

Review and share

Reports are saved locally after end. Read them before sending them anywhere. preview --format html shows the same view without ending the session.

shell

$ debugbrief end --format html --open
$ debugbrief open --html
$ debugbrief last --open

Find a previous session

list shows recorded sessions and show takes a full session id or an unambiguous prefix. Both accept --json.

Post a reviewed brief to a pull request

shell

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

The GitHub CLI is optional and never required by DebugBrief.

Evidence Explorer

Export a JSON report, then open it in the Explorer with the file picker or by dropping it on the page. Choose a generated report from .debugbrief/reports/, not a raw session file.

shell

$ debugbrief end --format json
# or inspect an active session without ending it
$ debugbrief preview --format json > report.json

Reports are parsed in the browser and held in memory until you clear them or reload the page. Report contents are never uploaded or saved to browser storage; only an explicitly chosen color theme is saved. One file up to 5 MiB, at most 2,000 entries per list.

JSON schema version 1 adds per-attempt commands, bounded stdout and stderr previews, truncation flags and current failures. Older unversioned reports still open, and missing command history is flagged. The Explorer shows what the report claims; it does not re-verify it.

Current reports attach a project-relative working directory to commands, verification, chronology and reproduce instructions. . means the project root. Older reports or locations that could not be recorded show an unknown directory; the Explorer does not assume the root.

Status and recovery

status shows the active session and any running captured command. If a process crashes, recover repairs stale state without deleting the session.

Immediately after a crash, cleanup may still hold the command lock. Wait briefly and retry status and recover; recovery refuses to clear a held lock. A lost result remains unknown rather than becoming a pass.

A separate supervisor stops the captured command's process group if the recorder is killed, including with SIGKILL. A lost command result stays unknown, and a child that deliberately starts its own session can outlive the capture.

shell

$ debugbrief status
$ debugbrief doctor --fix
$ debugbrief recover

doctor prints a health check and exits 0 when ready, 1 when usable with warnings and 2 on blocking issues. --fix only creates .debugbrief/ and adds it to .git/info/exclude.

Privacy and redaction

The project-root field shows the repository name by default. Pass --include-full-path only when you want the full root in a report. Absolute paths typed into commands, notes or captured output can still appear; hiding the project-root field does not scrub those paths.

Commands, output previews, titles and notes go through conservative, best-effort redaction before anything is written, unless you pass --no-redact. Common secret patterns are masked, but detection is not guaranteed. Review every report before sharing it.

DebugBrief sends no telemetry and uploads nothing. A command you choose to run can still use the network. Session directories use owner-only permissions where supported, writes are atomic, and commands are protected by session locks.

Configuration

An optional .debugbrief.toml in the project root sets defaults. A command flag wins over the file, and the file wins over the built-in default.

toml

default_mode = "pr"
timeout_seconds = 600
detail = "compact"

A missing file is ignored. A malformed file is ignored as a whole and flagged by debugbrief doctor. The config cannot enable the full project-root field; that requires the command flag. Paths inside recorded text are governed by the privacy limits above.

Limitations

No full-screen TUI capture, such as vim or htop.
No passive shell-history capture.
No guaranteed secret detection.
No native Windows or PowerShell support.
No inferred root cause or independent correctness audit.
No reproducible environment capture: redo uses the current environment.
Outside a Git repository, commands and notes still work, but Git state, changed files and Git-based correlation are unavailable.

Command reference

initSet up the project and show the workflow. Never starts a session.

start "<title>"Start a session and record the initial Git state.

note <text>Record an observation. Quoting is optional.

run [flags] -- <command>Run and capture a command.--timeout SECONDS --shell --verify --no-redact

redo [flags]Re-run the last captured command.--dry-run --yes --timeout SECONDS --verify --no-redact

cancel [--yes]Abandon the session. No report is written; the record is kept.

statusShow the active session and any running command.

doctor [--fix]Health check. Exit 0 ready, 1 usable with warnings, 2 blocking.

recoverRepair a broken or stale session pointer. Never deletes session data.

last [--open]Show or open the most recent report.

open [--last | --path PATH] [--html]Open a report in $EDITOR, or an HTML report in the browser.

list [--json]List recorded sessions.

show <session_id> [--json]Show one session. Accepts an unambiguous id prefix.

Troubleshooting

Command not found after installMake sure your installer's bin directory is on PATH. For pipx run pipx ensurepath; for uv run uv tool update-shell. Then open a new terminal.

A captured executable is missingInstall that executable in the environment used by run and check PATH. Installing DebugBrief does not install pytest, Node or your project dependencies.

Externally managed PythonUse pipx or uv, or install inside an activated virtual environment. Do not use sudo pip.

A captured command was interruptedRun debugbrief status, then debugbrief recover for stale state. Recovery keeps the session and never invents a command outcome.

A command needs more timeThe default timeout is 300 seconds. Raise it per command: debugbrief run --timeout 900 -- pytest -q.

No passing verification listedRun a recognized check, or declare your own with debugbrief run --verify -- ./check.sh. A failed or interrupted command cannot verify.

Report import fails in the ExplorerExport with --format json. Raw session files, unsupported schema versions, oversized lists and malformed JSON are rejected. A report that was already open stays open.

Full command reference on GitHub