Package the failure. Leave the branch alone.

BugParcel captures a backend failure with its Git state, request/fixtures, environment constraints, and failure contract so humans and coding agents can replay and independently verify a fix — without mutating the source branch.

What a parcel is

A parcel is a versioned, portable description of a failure. The local store is content-addressed (SHA-256) and append-only for status transitions. Today's vertical slice covers exact Git snapshot capture, generic process reproduction with a stable exit-code assertion, and CLI/MCP workflows for capture → reproduce → verify.

HEAD, branch hint, staged and unstaged diffs
Reproduction command + expected exit code / output contract
Optional fixtures restored at repository-relative paths
Allowlisted environment values and optional Docker image

CLI workflow

The bugparcel CLI is the local source of truth. Store path defaults to .bugparcel in the current directory, or whatever you set in BUGPARCEL_HOME.

$ bugparcel capture --name failing-auth -- npm test -- auth
$ bugparcel show <parcel-id>
$ bugparcel reproduce <parcel-id>
$ bugparcel verify <parcel-id> --patch ./fix.diff
$ bugparcel reduce <parcel-id> --output minimized-request.json

Isolation model

Reproduce, reduce, diagnose, propose, and verify all run in detached BugParcel worktrees. Source repositories are never changed by replay or verification. Cleanup removes only those worktrees.

Contract stays outside the candidate diff. Verification is honest because the acceptance contract is independent of the patch under test.

MCP tools for coding agents

bugparcel-mcp is a local stdio MCP server. Agents get the same ground truth humans capture — parcels, contracts, reproduction, diagnosis, proposed diffs, and cleanup.

bugparcel_list_parcelsList local manifests

bugparcel_get_parcelRead a full append-only manifest

bugparcel_get_contractCommand, expected failure, state, fixtures, env

bugparcel_captureCapture from a local Git repository

bugparcel_reproduceReplay in a fresh detached worktree

bugparcel_diagnoseContract + replay result + worktree path

bugparcel_propose_fixApply a unified diff only in a new worktree

bugparcel_verifyConfirm a patch clears the original failure

bugparcel_reduceMinimize JSON state while preserving the contract

bugparcel_cleanup_worktreesRemove BugParcel worktrees only

FastAPI adapter

The Python adapter writes a sanitized request/error event and invokes the local CLI on unhandled exceptions. Replay sets BUGPARCEL_REPLAY=1 so capture stays off during isolated runs. Captured contracts can require both the expected exit code and the original exception type in command output.

For coding agents

Machine-readable guidance lives at /llms.txt. Install with Homebrew, then attach bugparcel-mcp — see the agent guide.

Install with Homebrew →llms.txt for agents