BugProof

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 verify | Validate the Ed25519 signature on a .bug (standalon