man forkbomb

A single agent run is one draw. When it goes the wrong way, you find out late and start over. Forkbomb takes several draws at once, cheaply, and lets the tests you already trust pick the result. Forking uses APFS clonefile(2), so a fork costs metadata, not a copy of your repo. The name is the joke; :(){ :|:& };: is the classic shell fork bomb. This one stops at the number of forks you ask for.

Platform

macOS on APFS. Sandboxing uses Seatbelt.

Engines

claude-code (default, your Claude plan), api (API key) or hosted (live)

Judge

Your test command, run against each fork's patch in a fresh clone

Output

winner.patch, a full event log, a replayable run

Status

Pre-release. Install from source. 64 automated tests in the CLI's own suite.

License

MIT. Self-hosting is free and always will be.

• macOS on an APFS volume
• Node 22 or newer
• Xcode Command Line Tools
• Claude Code logged in (Pro or Max plan), or an Anthropic API key

Xcode Command Line Tools provide clang, which compiles a one-file clone helper on first run. For the default engine, Claude Code must be installed and logged in with a Pro or Max plan. For --engine api, you need an ANTHROPIC_API_KEY instead. For --engine hosted, you need a FORKBOMB_API_KEY and credit (see Hosted engine).

forkbomb doctor checks all of it:

# Clone and build$ git clone https://github.com/plvgger/forkbomb$ cd forkbomb && npm install && npm run build # Check the machine$ node dist/cli.js doctor # Run it$ node dist/cli.js run ./my-repo \    --task "fix the failing tests" \    --test "npm test" --ui

Credentials#

For the default engine, log Claude Code in once. Forkbomb uses whatever it is logged in with. For the API or hosted engine, put the key in ~/.forkbomb/.env or export it.

$ claude auth login

ANTHROPIC_API_KEY=...        # --engine apiFORKBOMB_API_KEY=forkbomb_sk_...   # --engine hosted

1. Check the machine

   $ forkbomb doctor

2. Prove the sandbox holds

   Optional. Forkbomb runs the isolation canary on its own before the first run on each Claude Code version. It takes about a minute.

   $ forkbomb canary

3. Start the race

   --task says what to do. --test decides who exits 0. --ui opens the live process tree on 127.0.0.1:4317.

   $ forkbomb run ./my-repo --task "fix the failing tests" --test "npm test" --ui

4. Review and ship the patch

   The passing fork's diff is saved as winner.patch in the run folder. Read it, then apply it. Or pass --apply next time and Forkbomb applies it for you.

   $ git -C ./my-repo apply ~/.forkbomb/runs/<id>/winner.patch

What a race looks like#

A real run from 2026-10-05: Claude Code on a Max plan, on the demo calc repo. The baseline had 4 of 14 tests passing. Four forks were made in 1.13 ms each. Fork 1.04 (rewriter) passed 14/14 first, the other 3 were killed, and the whole race took 38.7 s.

node dist/cli.js run ./calc --task "fix the failing tests" --test "node --test" --forks 4run · 4 forks × 2 rounds · claude-code · race · sandbox onbaseline: 4 passing, 10 failingfork()  4 copies of pid 1 in 1.13 ms each via apfs-clonefile  1.01 surgeon   1.02 root-cause   1.03 test-driven   1.04 rewriter  1.04 ✎ create calc.js  ·  $ node --test  1.04 PASS 14/14 · 94 lines  kill -9  1.01  1.02  1.03  (1.04 passed first)exit 0  1.04: 94 lines in 1 file. All 14 tests pass. 38.7s

Open the full replay of this run

1. 01fork()clonefile pid 1 into N forks
2. 02Raceone strategy per fork, in parallel
3. 03Judgeapply the patch to a fresh clone, run the suite
4. 04kill -9kill the losers, the passing fork exits 0
5. 05Re-forkno pass: the best fork becomes the next parent

1. fork()#

Forkbomb clones your repo once into pid 1, commits a base snapshot, and forks pid 1 into N copies with clonefile(2). On APFS a clone shares every data block with its parent until a fork writes, so forking costs metadata, not bytes. Off APFS, Forkbomb falls back to a plain copy.

forkbomb bench · MacBook Air (M2, 24 GB) · 80 MB node_modules tree, 4,400 files · 16 forks. ≈24× faster, ≈60× less disk. Run forkbomb bench ./my-repo to measure your own.

2. Race#

Each fork is an agent with a shell and a file editor, working in its own clone. Each gets a different strategy. Diversity is the point: eight copies with one strategy fail the same way eight times. Forks take strategies in this order and wrap around after twelve.

3. Judge#

A fork is judged by the patch it would ship, not by the state of its sandbox.

1. Take the fork's diff against the base snapshot.
2. Drop every change to tests and test config (see protected paths).
3. Apply what is left to a fresh clone of pid 1.
4. Run your test command there, under Forkbomb's own Seatbelt profile.
5. Score it. A clean exit only counts as a pass if no tests went missing compared with the baseline.

Hacks to ignored files such as node_modules or build output never reach the fresh clone, so they never count. The judge is designed against the common ways an agent games a suite. It is still being hardened. Read the winning patch before you ship it.

4. kill -9#

In race mode, the first fork to pass the full suite exits 0 and the rest are killed mid-thought. In best mode, every fork finishes and the smallest passing diff wins. Killed forks' clones are deleted unless you pass --keep-forks.

5. Re-fork#

If nobody passes, the best fork's verified state (pid 1 plus its patch) becomes the parent of the next round, with a note on where it left off. --rounds caps how many times this happens. If the last round still has no pass, Forkbomb saves the best partial patch as best.patch.

claude-code#

Each fork is a headless Claude Code session (claude -p) on whatever Claude Code is logged in with. Forks count against your plan's usage limits, and eight forks use them about eight times as fast as one session. Each fork runs with:

• --safe-mode: no CLAUDE.md, hooks, plugins or MCP.
• No user or project settings, so a repo's own .claude/settings.json can't loosen anything.
• Claude Code's sandbox for Bash: writes stay in the clone, no network, credential folders unreadable, no unsandboxed escape hatch.
• Permission rules that deny the file tools on credential folders and .git.
• No API keys in its environment.

api#

Forkbomb's own tool loop on the Messages API, with ANTHROPIC_API_KEY. The default model is claude-opus-5-5 at medium effort. Shell commands run under Forkbomb's Seatbelt profile. The text editor runs in Forkbomb's process and re-checks every path: no .., no symlinks out of the clone or into .git, no writing through hard links.

hosted#

The same tool loop and the same sandbox as api, but the model is Forkbomb's own GPU coding model behind an OpenAI-compatible gateway, paid with credit from burning $FORKBOMB. Details in Hosted engine.

Set it up#

1. 01

   Create a workspace

   In the app (opens at launch). You get a workspace id, an API key that starts with forkbomb_sk_, and your burn memo. The key is shown once. Only a hash of it is stored.

2. 02

   Add credit

   Burn $FORKBOMB with your workspace memo. See Burn for compute.

3. 03

   Give the CLI the key

   FORKBOMB_API_KEY=forkbomb_sk_...

4. 04

   Check the balance, then race

   $ forkbomb credits$ forkbomb run ./my-repo --task "fix the failing tests" --test "npm test" --engine hosted

--model is ignored with this engine: the gateway picks the model. Before it makes a single fork, the CLI asks the gateway for your balance and stops if it is zero.

Base URL#

The CLI talks to https://forkbomb.fun/api/v1. Set FORKBOMB_HOSTED_URL to point it somewhere else, for example a gateway you run yourself. The URL must be https (plain http only for localhost) and must not carry credentials. Redirects are refused, so the key can't be bounced to another host.

Credits and pricing#

Hosted compute is priced per million input tokens and per million output tokens, in USD. The current prices come back from GET /api/v1/me and forkbomb credits prints them. Prices are not final until the pool is live.

• Each request first reserves the most it could cost: the estimated input plus max_tokens.
• When the model answers, the real cost is charged and the rest of the reservation is returned.
• A request that fails upstream is charged nothing.
• The balance can't go below zero. The database refuses it.

forkbomb creditsworkspace  <label> (ws_…)credit     $<balance>pricing    $<in> / 1M input tokens · $<out> / 1M output tokens · model <model>top up     burn $FORKBOMB at https://forkbomb.fun/app

Out of credit (402)#

When a request would cost more than the balance, the gateway answers 402 insufficient_credits and charges nothing. In a race, the fork that got the 402 stops with “out of credit: burn $FORKBOMB to top up”. The forks share one balance, so no other fork makes another model call after that. Forks that stopped are still judged on what they changed so far, so a fork that already passed can still exit 0.

429 and 5xx answers (except 503) are retried up to four times with backoff, honoring Retry-After. 401, 402 and 503 are not retried.

Run Forkbomb on code you'd be comfortable letting an agent work on. The judge (git and your test command) always runs under Forkbomb's own Seatbelt profile, whichever engine drove the forks. With the hosted engine, the gateway only sends model tokens back; it never runs anything on your machine.

The isolation canary#

With the claude-code engine, Forkbomb doesn't assume the sandbox holds. Before the first run on each Claude Code version, it starts a real session in a throwaway workspace, tells it to escape, and checks the results. Forks only start if every escape failed. The result is cached in ~/.forkbomb/canary.json. Run it any time with forkbomb canary.

Read the full security model

forkbomb run [repo] --task "..." --test "cmd"   race forks on a repoforkbomb bench [dir] --forks 16                 clonefile vs copy, measuredforkbomb replay <run-dir>                       watch a recorded runforkbomb export <run-dir> <out-dir>             static replay you can host anywhereforkbomb doctor                                 check the machineforkbomb credits                                hosted credit balance and pricingforkbomb canary                                 prove Claude Code forks can't escape

forkbomb run#

Usageforkbomb run [repo] --task "…" --test "cmd" [options]

Starts a race on a repo. repo defaults to the current directory. Exits 0 when a fork passes the full suite, 1 otherwise. With --ui, the live view stays up after the run until you press Ctrl-C.

forkbomb bench#

Usageforkbomb bench [dir] [--forks 16] [--no-copy] [--json]

Forks the same workspace with clonefile and with a plain copy, and prints time and disk for each. Extra disk is measured from free space before and after, so other activity on the machine shows up as noise.

forkbomb replay#

Usageforkbomb replay <run-dir | events.jsonl> [--port 4317] [--no-open]

Serves the tree view for a recorded run on 127.0.0.1 and plays it back from the event log.

forkbomb export#

Usageforkbomb export <run-dir> <out-dir>

Writes a static, self-contained replay: index.html, app.js, style.css, data.js and a copy of events.jsonl. Host it anywhere that serves static files. The replay on this site is built from an export of the run above.

forkbomb doctor#

Usageforkbomb doctor

Checks the machine and prints one ok, info or FAIL line per check, with a hint on failures. See Requirements for the full list.

forkbomb credits#

Usageforkbomb credits [--json]

Asks the hosted gateway for your workspace, balance and pricing, using FORKBOMB_API_KEY. Exits with a hint if no key is set. See Credits and pricing.

forkbomb canary#

Usageforkbomb canary [--claude-bin PATH] [--model ID]

Runs the isolation canary against the installed Claude Code and prints each check. Exits 0 only if every escape failed.

~/.forkbomb/  .env                  ANTHROPIC_API_KEY / FORKBOMB_API_KEY (optional)  canary.json           last canary result, per Claude Code version  runs/    20261005-155223/    one folder per run, YYYYMMDD-HHMMSS      events.jsonl      every event in order; replay and export read it      winner.patch      the passing fork's diff (best.patch if none passed)      body/             pid 1: clean clone of your repo plus the base snapshot      heads/<id>/       the final fork's clone; killed forks are deleted      state/<id>/       pid 1 plus the final patch, verified by the judge

Pass --keep-forks to keep every fork's clone. Pass --runs-dir to put runs somewhere else, as long as it is outside the repo.

winner.patch#

A plain git diff against your repo. Test and test-config edits are already stripped. This is the start of the 94-line patch from the run above:

diff --git a/calc.js b/calc.jsindex 4e2ff7c..c666268 100644--- a/calc.js+++ b/calc.js@@ -1,19 +1,25 @@ // A small arithmetic evaluator: + - * / ^, parentheses, unary minus, decimals. // evaluate("2 + 3 * 4") === 14+//+// Precedence (lowest to highest): + -  <  * /  <  unary -  <  ^ (right-assoc).  export function tokenize(src) {   const tokens = [];   let i = 0;   while (i < src.length) {     const c = src[i];-    if (c === " ") {+    if (/\s/.test(c)) {       i++;       continue;     }-    if (/[0-9]/.test(c)) {+    if (/[0-9.]/.test(c)) {       let j = i;       while (j < src.length && /[0-9.]/.test(src[j])) j++;-      tokens.push({ type: "num", value: parseFloat(src.slice(i, j)), pos: i });+      const text = src.slice(i, j);

events.jsonl#

One JSON object per line, each stamped with the time since the run started. The live view, replay and export all read this file. Event names predate the rename: a fork is a head, a kill is a sever.

A good --task#

• State the outcome, not the method. Strategies already vary the method across forks.
• Name what you know. The file, the function, the behaviour that is wrong.
• Say what must not change. A public API, a file format, a dependency.
• Keep it to one job. Two unrelated fixes in one task split the forks' attention.

--task "make the parser better"

--task "parseDate in src/date.ts throws on a trailing Z. Parse it as UTC. Keep the signature."

A good --test#

• It must fail now. Forkbomb runs it on the untouched repo first. If it already passes, there is nothing to race for and the run stops.
• Fast and deterministic. It runs once for the baseline and once per judged fork. Flaky tests pick random winners.
• Offline. The judge has no network beyond loopback. Install dependencies before the run; forks can't install them either.
• Scoped. Run the tests that matter for the task, not the whole slow suite.

Forkbomb reads pass and fail counts from node:test, vitest, jest, mocha, pytest, unittest, cargo test and go test output, which gives partial credit and lets the best partial fork seed the next round. With any other runner, the exit code decides: pass or fail, nothing in between.

Protected paths#

Forks can't win by editing the tests. By default, changes matching these globs are dropped from every patch before it is judged. Add more with --protect; turn the defaults off with --no-default-protect.

**/*.test.***/*.spec.***/test/****/tests/****/__tests__/****/test_*.py**/*_test.py**/*_test.go**/conftest.py**/package.json**/package-lock.json**/pnpm-lock.yaml**/yarn.lock**/vitest.config.***/vite.config.***/jest.config.***/.mocharc***/pytest.ini**/pyproject.toml**/setup.cfg**/tox.ini**/Cargo.toml**/go.mod**/Makefile

1. 01

   Create a workspace

   In the app. It gives you a workspace id like ws_…, an API key (shown once) and your memo: forkbomb:<workspaceId>.

2. 02

   Burn from your wallet

   One Solana transaction that burns $FORKBOMB (an SPL burn or burnChecked, Token or Token-2022 program) and carries exactly one memo, forkbomb:<workspaceId>, with nothing else in it. The app builds this transaction for you.

3. 03

   Verify

   The app sends the transaction signature to POST /api/burns/verify. You can call it yourself with any signature; it is safe to repeat.

4. 04

   Credit lands

   Once the transaction is finalized and checks out, the workspace is credited and the burn shows up on the public ledger.

What the verifier checks#

Everything is read back from the chain. Nothing you send besides the signature is trusted.

1. The transaction exists on mainnet, is finalized, and did not fail.
2. It burns the $FORKBOMB mint, in a top-level or inner instruction. Burns of any other token don't count.
3. Each burned token account's balance fell by exactly the amount burned.
4. There is exactly one memo starting with forkbomb:, and it is exactly forkbomb:<workspaceId>.
5. The workspace in the memo exists.
6. There is a price for the burn's block time (next section).

How a burn is priced#

The server samples the token's USD price every 5 minutes (Jupiter, with DexScreener as a fallback). For a burn at block time T, the price is the lowest of three numbers:

• the time-weighted average price from T − 15 min to T + 5 min,
• the first sample at or after T,
• the last sample at or before T.

USD value = tokens burned × that price. Credit is the USD value at the credit rate, which is 1.0 by default: one dollar of burned value buys one dollar of compute credit, rounded down to the micro-dollar. Pricing uses the burn's own block time, so verifying later changes nothing, and taking the lowest of three numbers means a short price spike can't be farmed. A burn with fewer than two samples in its window is rejected as too_old_for_price, unless it is under 10 minutes old; then the price is the lower of the latest sample and a live quote.

Verified once, credited once#

The transaction signature is the key. Verifying the same signature again returns the stored record with status already_credited. Two verifies racing each other still credit once. A single burn worth more than a per-burn cap is recorded with status review (HTTP 202) and credits nothing until a person checks it.

What credit is, and isn't#

The full terms are on the terms page.

The public ledger#

Every verified burn is public on /burns and from GET /api/ledger: signature, wallet, amount, price, USD value, credit and block time. Workspace ids are left out. Every row can be checked on Solana with its signature.

Gateway base URL

https://forkbomb.fun/api/v1

Auth

Authorization: Bearer forkbomb_sk_… on /api/v1/*

Errors

OpenAI shape: {error:{message,type,code}}

Status

Hosted pool: live. Burns open at token launch.

{  "error": {    "message": "Insufficient credits: this request needs up to $<max cost> and the workspace has $<balance> remaining. Burn tokens to add credit.",    "type": "billing_error",    "code": "insufficient_credits"  }}

$ curl https://forkbomb.fun/api/v1/chat/completions \    -H "Authorization: Bearer $FORKBOMB_API_KEY" \    -H "Content-Type: application/json" \    -d '{"model":"forkbomb-hosted","messages":[{"role":"user","content":"hello"}]}'

{  "workspace": { "id": "ws_…", "label": "…", "createdAt": "…" },  "credits": { "balanceMicroUsd": <integer>, "balanceUsd": <number> },  "pricing": { "inputPerMTokUsd": <number>, "outputPerMTokUsd": <number>, "model": "…" }}

// request{ "signature": "<base58 transaction signature>" } // 200 credited or already_credited · 202 held for review{  "burn": {    "signature": "…", "workspaceId": "ws_…", "owner": "<wallet>", "mint": "…",    "amountUi": "…", "priceUsd": "…", "usdValue": "…", "creditMicroUsd": <integer>,    "slot": <integer>, "blockTime": "…", "verifiedAt": "…",    "status": "credited" | "already_credited" | "review"  }}

{  "burns": [    { "signature": "…", "owner": "<wallet>", "mint": "…", "decimals": <integer>,      "amountUi": "…", "priceUsd": "…", "usdValue": "…", "creditMicroUsd": <integer>,      "slot": <integer>, "blockTime": "…", "status": "credited" | "review" }  ],  "totals": { "burnedUi": "…", "burnedUsd": "…", "burns": <integer>, "creditedMicroUsd": <integer> },  "nextCursor": "…" | null}

{  "mint": "…" | null,  "latest": { "ts": "…", "priceUsd": "…", "source": "jupiter" | "dexscreener" } | null,  "twap": { "windowMinutes": 15, "priceUsd": "…", "samples": <integer> } | null}

// request (label optional, up to 64 characters){ "label": "my laptop" } // 201{ "workspace": { "id": "ws_…", "label": "my laptop", "createdAt": "…" },  "apiKey": "forkbomb_sk_…",  "burnMemo": "forkbomb:ws_…" }