BugProof

Executable bugs, not bug reports.

Capture a failing command into a portable .bug artifact that anyone can replay on their machine — same code, same env, same failure. Cryptographically signable. Cross-platform. Zero containers required.

https://github.com/user-attachments/assets/2315cfee-3ccf-40d7-830e-3a3d23731ab8

Why BugProof

"Works on my machine" is not a bug report.

Filing a backend or CLI bug today usually looks like this:

• A screenshot of a terminal
• A copy-pasted stack trace
• A list of probably relevant files
• A best-guess description of how the reporter ran the thing

Then the maintainer spends hours reconstructing the failure: matching versions, replicating the env, finding the right command, guessing at config. Most of that time is wasted.

BugProof captures the bug — not the description of it. One command produces a single .bug file containing the source snapshot, the exact command, the environment schema, the failure fingerprint, and replay metadata. Another developer runs bugproof replay bug.bug and reproduces the failure deterministically.

Think of it as Git for bugs: a portable, content-addressable, verifiable artifact that turns "can you reproduce?" into a one-liner.

Highlights

• One-command capture. Wrap any failing command with bugproof capture -- and ship the result.
• Deterministic replay. Source, env, command, and fingerprint travel together. Verdict is automatic.
• No Docker. No daemon. Uses native OS primitives — Linux namespaces, Windows Job Objects, macOS Seatbelt.
• Cryptographic signatures. Ed25519 sign/verify built in. Tamper-evident artifacts via bugproof keygen / --sign / verify.
• Self-healing replay. --self-heal auto-installs missing npm/pip deps in the sandbox and retries.
• Best-effort credential redaction. Env vars are scanned via pattern-matching + Shannon entropy. Known secret shapes (API keys, tokens, JWTs) are caught; low-entropy passwords and binary credentials may still leak.
• Multi-language. Detects Node.js, Python, Ruby, Go, Rust, Java, C/C++, .NET, Kotlin build context automatically.
• Cross-platform. Win ↔ Linux ↔ macOS replay, with command/env translation and architecture-mismatch guardrails.

Install

npm install -g bugproof

Requirements: Node.js 18+ and Git. Optional language toolchains (Python, Java, Go, Rust, …) are only needed if your captured command uses them.

Run a one-off health check after install:

bugproof doctor

GitHub Action — Capture CI Failures Automatically

Add a single step to any GitHub Actions workflow to auto-capture flaky/failing commands as .bug artifacts.

- name: Capture flaky test
  uses: sidinsearch/BugProof/.github/actions/bugproof-action@main
  with:
    command: 'npm test -- --run flaky-suite'
    name: flaky-test-failure
    timeout: 300000

How it works: The action installs bugproof from npmjs.org (npm install -g bugproof) → wraps your command with bugproof capture → on failure, the .bug artifact is uploaded to the Actions run. Developers download and repro locally with bugproof replay.

Use cases:

• Flaky CI tests: Capture the exact failure for local debugging
• Cross-platform failures: A test passes on Linux CI but fails on macOS — capture the failure on both and diff
• Intermittent crashes: bugproof capture -- node app.js bundles the crash state, env, and source

All inputs:

The action lives at .github/actions/bugproof-action/action.yml in this repo. Reference it via uses: sidinsearch/BugProof/.github/actions/bugproof-action@main. BugProof is always installed from npmjs.org — no GitHub Packages token needed.

MCP Server — AI-Agent Integration

BugProof ships a built-in MCP (Model Context Protocol) server that exposes 10 tools plus Resources and Prompts for AI agents. Listed on the Official MCP Registry as io.github.sidinsearch/bugproof.

Setup

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "bugproof": {
      "command": "npx",
      "args": ["-y", "bugproof", "mcp"]
    }
  }
}

Cursor

Add to Cursor MCP config (Settings → Features → MCP):

{
  "mcpServers": {
    "bugproof": {
      "command": "npx",
      "args": ["-y", "bugproof", "mcp"]
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": {
      "bugproof": {
        "command": "npx",
        "args": ["-y", "bugproof", "mcp"]
      }
    }
  }
}

With bugproof installed globally

If you already have bugproof globally (npm install -g bugproof), omit npx -y:

{
  "mcpServers": {
    "bugproof": {
      "command": "bugproof",
      "args": ["mcp"]
    }
  }
}

No separate MCP install needed. npx -y bugproof mcp auto-downloads from npmjs.org and starts the server over stdio.

Tools

Resources

AI agents can read .bug artifact contents directly via resource URIs:

• bugproof://artifact/{path} — Read the raw .bug artifact (base64-encoded ZIP)

Prompts

Pre-built workflows for common AI agent tasks:

Example AI session

User:   Capture the failing test and tell me what went wrong
Agent:  [calls bugproof capture -- npm test -- --run flaky-suite]
        [calls bugproof inspect on the result]
        "The test failed with a timeout. Fingerprint matches a known
         Redis-unreachable pattern. Here's the captured stderr..."

The MCP server communicates over stdio (JSON-RPC 2.0). It shells out to the local bugproof CLI with --json output and returns structured results with both human-readable summaries and raw data. If bugproof isn't installed, npx -y fetches it from npmjs.org — no global install required.

AI Agent Skill

BugProof ships a distributable AI Agent Skill that teaches AI coding agents (Claude Code, Cursor, OpenCode, OpenClaw, Gemini CLI, GitHub Copilot, and others) how to use BugProof effectively. The skill follows the open Agent Skills standard — build once, use across any compatible agent.

What the Skill Does

When loaded, the skill gives AI agents complete knowledge of:

• All 14 BugProof commands with flags and examples
• Capture, replay, diff, and inspection workflows
• Cross-platform replay patterns
• MCP server configuration
• Best practices for naming, security, and artifact management
• 8 real-world examples (Node.js, Python, Go, Java, CI/CD, cross-platform, flaky tests)

How AI Agents Use It

Agents auto-load the skill when users mention:

• "capture this bug"
• "replay the bug"
• "reproduce this failure"
• "share this bug"
• ".bug file"
• "works on my machine"
• "executable bug"

Or invoke directly: /bugproof

Install the Skill

Option 1: Clone This Repository

# Clone the BugProof repository
git clone https://github.com/sidinsearch/BugProof.git

# Copy the skill to your agent's skills directory
# Claude Code:
cp -r BugProof/skills/bugproof ~/.claude/skills/

# OpenCode:
cp -r BugProof/skills/bugproof ~/.config/opencode/skills/

# OpenClaw:
cp -r BugProof/skills/bugproof ~/.agents/skills/

# Cursor:
cp -r BugProof/skills/bugproof ~/.cursor/skills/

Option 2: Download the Skill Directly

# Download just the skill
curl -L https://github.com/sidinsearch/BugProof/archive/refs/heads/main.tar.gz | tar xz
cp -r BugProof-main/skills/bugproof ~/.claude/skills/

Skill Structure

skills/bugproof/
├── SKILL.md                    # Main instructions (required)
├── reference/
│   └── commands.md             # Full command reference
└── examples/
    └── usage-examples.md       # Real-world usage examples

Supported AI Agents

The skill follows the open Agent Skills specification — any agent that supports the standard can use it.

60-Second Quick Start

# 1. Reproduce a failure
$ npm test
FAIL  Tests failed because Redis was unreachable.

# 2. Capture it
$ bugproof capture -- npm test
  ✔  Artifact captured!
  Path        ./bug_1778049738215.bug
  Files       42 files (28.4 KB)
  Fingerprint sha256:c8b3...

# 3. Share the file (Slack, email, gist, attachment...)

# 4. Anyone replays it on their machine
$ bugproof replay bug_1778049738215.bug
  ✔  REPRODUCTION CONFIRMED
  Exit code    exit 1 (match)
  Verdict      Reproduction confirmed (exact fingerprint match)

Optional flow:

$ bugproof inspect bug.bug        # peek at the contents
$ bugproof diff old.bug new.bug   # what changed between two captures
$ bugproof share bug.bug          # publish as a GitHub Gist

Commands

BugProof ships 14 commands. Every command supports --help and --json for machine-readable output.

bugproof capture [command...]

Run a command end-to-end and bundle the failure as <name>.bug.

bugproof capture -- npm test
bugproof capture -n auth-crash -d "Login fails on expired session" -- node server.js
bugproof capture -o ./bugs/ -- npm test
bugproof capture --include-untracked -- python app.py
bugproof capture -x "*.log" -x "node_modules/**" -- go test ./...
bugproof capture --timeout 600000 -- java -cp . Main
bugproof capture --include-compiled -- mvn test    # force include .class/.jar files
bugproof capture --sign --signer "alice@example.com" -- ./run.sh
bugproof capture --json -- node script.js

Default behavior: Without -n, artifacts are named bug_<timestamp>.bug. With .bugproofrc nameTemplate configured, the template is used instead. Without -o, artifacts are saved in the current directory.

bugproof replay <artifact>

Re-execute the captured artifact and compare results.

bugproof replay bug.bug
bugproof replay bug.bug --sandbox isolated
bugproof replay bug.bug --self-heal
bugproof replay bug.bug --verify-signature
bugproof replay bug.bug --source-dir .
bugproof replay bug.bug --json

Replay isolation: Replay always runs in an isolated temp directory. Files come from either: (1) git worktree/clone at the captured commit, (2) current directory's git repo (if original path is inaccessible), or (3) the artifact's bundled files/ snapshot. The current directory is never read for source files.

bugproof keygen / verify — Cryptographic Provenance

Sign artifacts with Ed25519 (RFC 8032). Built on Node's native crypto — no external deps.

# One-time: create your signing key
bugproof keygen
# → writes default.pub / default.key to ~/.bugproof/keys/

# Capture with a signature
bugproof capture --sign --signer "alice@example.com" -- npm test

# Verify a received artifact
bugproof verify bug.bug
  ✔  SIGNATURE VALID
  Algorithm   ed25519
  Fingerprint 179721ef7e63f6b3
  Signed at   2026-05-10T22:09:30Z
  Signer      alice@example.com

# Enforce signatures at replay time
bugproof replay --verify-signature bug.bug

The signature covers a canonical hash of the manifest, the failure fingerprint, and the SHA-256 of every file in the bundle. Tampering with source, output, exit code, or metadata invalidates the signature.

Note: identity/PKI is intentionally out of scope. Trust is established by comparing the embedded public-key fingerprint against one you know (gist pinning, team wiki, key server, etc.).

bugproof watch [command...]

Transparent wrapper. Runs the command normally; only captures if it fails. Drop-in replacement for any command you'd otherwise hand-run.

bugproof watch -- npm test
bugproof watch -o ./bugs -- python app.py
bugproof watch --always -- node script.js    # capture even on success

bugproof inspect <artifact> / diff <a> <b>

bugproof inspect bug.bug                          # manifest, fingerprint, file list, env schema
bugproof diff captured-v1.bug captured-v2.bug     # what changed between two captures

bugproof share <artifact>

Publish an artifact as a GitHub Gist. Respects HTTPS_PROXY / HTTP_PROXY for corporate networks.

bugproof share bug.bug
bugproof share --public bug.bug

Requires GITHUB_TOKEN (or BUGPROOF_GITHUB_TOKEN) with gist scope.

bugproof init / prune / doctor

bugproof init       # scaffold .bugproofrc in the current directory
bugproof prune      # garbage-collect orphan BugBox temp directories
bugproof doctor     # check OS support for sandbox isolation (namespaces, Job Objects, Seatbelt)

Configuration (.bugproofrc)

Generated by bugproof init. All fields are optional.

{
  "exclude": ["node_modules/**", "dist/**", "*.bug"],
  "outputDir": ".",
  "timeout": 300000,
  "skipSecrets": false,
  "includeUntracked": false
}

Smart Source Strategy

BugProof keeps artifacts small even on heavy codebases:

Git is strongly encouraged but not required.

Compiled Language Support

BugProof auto-detects compiled languages and bundles build artifacts automatically:

How it works: When BugProof detects a compiled language project (via pom.xml, go.mod, Cargo.toml, etc.) and finds compiled artifacts in standard build directories, it automatically includes them. No flag needed.

Use --include-compiled to force inclusion even when auto-detection misses something, or for edge cases.

Sandbox & Isolation Model

BugProof runs replayed commands in a layered sandbox — Docker-like isolation built on native OS primitives.

Three sandbox levels are exposed via --sandbox:

• workspace (default) — minimal isolation, fast. Good for trusted artifacts.
• isolated — namespace + temp isolation. Recommended for untrusted artifacts.
• full — all layers including network deny + resource limits.

Caveat: On Windows, isolated and full are best-effort hardening, not VM-grade containment. For artifacts from fully untrusted sources, replay inside a dedicated VM.

Environment Snapshot

Capture-time runtime versions are recorded and diffed on replay:

  Environment Mismatches
    •  node version mismatch: captured 18.0.0, current 22.1.0
    ✘  python 3.11.0 was available at capture but is not installed now.

Tracked: Node.js, Python, Ruby, Go, Rust, Java, npm, pip, OS platform, architecture.

Cross-Platform Replay

The translation layer normalizes commands (python3 ↔ python, gradlew ↔ gradlew.bat, make ↔ mingw32-make, shell paths). Architecture mismatches (x64 ↔ arm64) trigger explicit warnings with Rosetta/translation advice.

Security Model

Use --skip-secrets only when you've audited the environment yourself.

File Association

Windows

Registered under HKCU\Software\Classes\.bug → BugProof.Artifact with open command node <package>/dist/cli.js replay "%1".

Linux

Registers MIME application/x-bugproof, a bugproof.desktop handler, and a user-level icon entry in ~/.local/share/icons/hicolor/.

macOS

Best-effort via the bundled script. Re-run manually if Finder association doesn't take:

bash scripts/bugproof-file-association-macos.sh

Architecture

bugproof/
├── src/
│   ├── capture/          # Execution + env snapshot + language detection + packaging
│   ├── replay/           # Restore + sandbox orchestration + verdict + self-heal
│   ├── sandbox/          # OS-specific isolation (filesystem, network, process)
│   ├── share/            # Gist publisher
│   ├── diff/             # Two-artifact diff engine
│   ├── config/           # .bugproofrc loader and validation
│   ├── utils/            # signing, secrets, fingerprint, dependencies, security, …
│   └── cli.ts            # Commander entrypoint (14 commands)
├── tests/                # 40 suites / 502 tests (Jest)
├── scripts/              # Postinstall, e2e matrix, file-association helpers
└── .github/workflows/    # CI/CD (tri-platform matrix, signed npm publish)

Contributing

PRs welcome. See CONTRIBUTING.md for guidelines, dev setup, and the test matrix expectations. Every PR runs the full tri-platform CI; please add tests for new behavior.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).