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