# BugParcel

> Local-first failure parcels for coding agents. Capture a backend failure with Git state, fixtures, environment constraints, and an independent verification contract - then reproduce and verify fixes in detached worktrees without mutating the source branch.

Homepage: /
Docs: /docs
Install: /docs/install
Agent guide: /docs/llms
This file: /llms.txt

## Install

```bash
brew tap AayushGokhale2005/bugparcel
brew trust AayushGokhale2005/bugparcel
brew install bugparcel
bugparcel --version
# bugparcel 0.1.1
```

Default store: `./.bugparcel` (override with `BUGPARCEL_HOME`).

## CLI

```bash
bugparcel capture --name <name> -- <command...>
bugparcel show <parcel-id>
bugparcel reproduce <parcel-id>
bugparcel verify <parcel-id> --patch ./fix.diff
bugparcel reduce <parcel-id> --output minimized.json
```

Capture records HEAD, staged/unstaged diffs, the reproduction command, expected exit code / output contract, optional fixtures (`--fixture-file`), allowlisted env (`--env KEY=VALUE`), and optional `--docker-image`.

## Isolation rules (critical)

- Reproduce, reduce, diagnose, propose, and verify run only in detached BugParcel worktrees.
- Never apply patches to the user's source branch.
- `bugparcel_cleanup_worktrees` removes only BugParcel worktrees.

## MCP server

Binary: `bugparcel-mcp` (stdio). Set `BUGPARCEL_HOME` to the same store humans use.

Client config:

```json
{
  "mcpServers": {
    "bugparcel": {
      "command": "bugparcel-mcp",
      "env": { "BUGPARCEL_HOME": "./bugparcel-runs" }
    }
  }
}
```

### Tools

- `bugparcel_list_parcels` - list local manifests
- `bugparcel_get_parcel` - full append-only manifest
- `bugparcel_get_contract` - command, expected failure, state, fixtures, env
- `bugparcel_capture` - capture from a local Git repo (`repository_path`, `command`, optional env/state/docker)
- `bugparcel_reproduce` - replay in a fresh detached worktree
- `bugparcel_diagnose` - contract + replay result + worktree path
- `bugparcel_propose_fix` - apply a unified diff only in a new worktree
- `bugparcel_verify` - confirm a patch clears the original failure (`parcel_id`, `patch_path`)
- `bugparcel_reduce` - minimize JSON state while preserving the contract
- `bugparcel_cleanup_worktrees` - remove BugParcel worktrees only

## Recommended agent loop

1. `bugparcel_list_parcels` or `bugparcel_get_contract`
2. `bugparcel_diagnose` / `bugparcel_reproduce`
3. Inspect the returned worktree; do not edit the source branch
4. `bugparcel_propose_fix` with a unified diff, or `bugparcel_verify` with a patch file
5. `bugparcel_cleanup_worktrees` when finished

## FastAPI adapter

Python middleware captures sanitized request/error events on unhandled exceptions and invokes the local CLI. During isolated replay set `BUGPARCEL_REPLAY=1` so capture stays off. See /docs and bugparcel-core/sdks/python/bugparcel-fastapi.

## Optional docs for humans

- /docs - concepts, CLI, isolation, MCP overview
- /docs/install - Homebrew install steps
- /docs/llms - how agents should use this site and MCP