**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://www.npmjs.com/package/bugproof)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://nodejs.org/)
[]()
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
```bash
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:
```bash
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.
```yaml
- 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**:
| Input | Required | Default | Description |
|---|---|---|---|
| `command` | โ
| โ | Command to capture (e.g. `npm test`) |
| `name` | โ | `bug_