processfork 1.0.10

fork() for AI agents — snapshot, branch, and merge live agent state.

ProcessFork

git for AI agents. Snapshot, fork, and merge live LLM sessions in 8 ms.

_{↑ Replay it locally: asciinema play demo/processfork-demo.cast}

---

Why

You're 4 hours into a refactor with Claude Code. The agent has read 200 files, run 47 tests, opened a database, started a dev server. Then it suggests a destructive change.

Today: lose everything, undo by hand, or restart. With ProcessFork: pf snapshot → 8 ms → safe. Try 12 alternatives in parallel, merge the winner back, ship the whole session to a teammate.

It's git — snapshot, branch, merge, push, clone — but for live AI agent state.

Highlights

• ⚡ 8 ms snapshots. Full agent state — model + KV-cache + files + tools + reasoning — into one content-addressed .pfimg.
• 🌳 Real fork & merge. 12 parallel attempts share storage automatically (CoW). Merge the winner with a real 3-way diff (files, tools, trace) — git-style <<<<<<< markers and all.
• 🔒 Won't double-send your email. HMAC-chained tool-call ledger; restored agents see prior side-effects as facts, not as actions to re-issue. (ACRFence-resistant.)
• 🤝 Drop-in for Claude Code, LangGraph, OpenInterpreter, vLLM, SGLang, AutoGen, CrewAI.
• 📦 Single binary, MIT, Rust core, Python + TypeScript SDKs. 200+ tests.

Quick start (60 seconds)

# install the CLI:
cargo install processfork                      # → `pf` on your $PATH

# snapshot a directory:
mkdir /tmp/sandbox && echo "fn main() {}" > /tmp/sandbox/main.rs
pf snapshot --agent-id demo --fs-root /tmp/sandbox
# → sha256:1c2497b0…   ⏱ 8 ms

# edit something, snapshot again, see the diff:
echo "fn main() { println!(\"hi\") }" > /tmp/sandbox/main.rs
pf snapshot --agent-id demo --fs-root /tmp/sandbox --name v2
pf log
pf diff <first-cid> <second-cid>

Prefer Python? pip install processfork. TypeScript? npm install @processfork/sdk.

The full 60-second demo (snapshot → fork ×12 → merge → push → clone on a fresh store) is bash demo/script.sh. Runs end-to-end on a laptop. No GPU, no API keys.

When you'd reach for it

Situation	Command
Agent about to do something destructive	pf snapshot pre-rm-rf
Stuck — want to try 12 approaches in parallel	pf fork -n 12 --explore "fix bug"
Hand a complex session to a teammate	pf push hf://you/session-name
Time-travel debug ("when did it go wrong?")	pf log then pf checkout <CID>
RL rollout fabric for agent training	snapshot, fan out, score, merge

Use it with your stack

Adapter	Status	What it gives you
Claude Code	✅ ships now	/snapshot, /fork, /merge slash-commands inside any session
LangGraph	✅ ships now	drop-in BaseCheckpointSaver (full 4-layer, not just state dict)
OpenInterpreter	✅ ships now	interpreter.snapshot("pre-rm-rf") then .checkout("pre-rm-rf")
AutoGen	✅ ships now	atomic snapshot across a whole agent group's state
CrewAI	✅ ships now	CrewMemory drop-in; every step time-travelable
vLLM	✅ ships now	bit-exact KV-cache snapshot/restore (V0 + V1 engine via collective_rpc)
SGLang	✅ ships now	live RadixCache k_buffer/v_buffer capture, mock-mode parity tests

How it works

ProcessFork captures the five things that together make up a live agent — atomically — into one content-addressed file:

Layer	What it captures
Model	LoRA / IA³ / full-finetune weight diffs, in-place TTT updates
Cache	Paged KV-cache, content-addressed per page (CoW across forks)
World	Filesystem, env, in-flight subprocesses, browser DOM
Effects	Append-only ledger of irreversible tool calls (HMAC-chained)
Trace	Chat + tool-call message log

Identical content shares storage automatically — 12 parallel forks use ~1.5× the space of one, not 12×. The merge engine handles each layer with the right algorithm: git-style 3-way diff for files, TIES + DARE for model weights, an HMAC chain that defends against semantic-rollback attacks (ACRFence), and an LLM-summarized "what branch B learned" patch injected into branch A's reasoning trace without re-prefilling the cache.

→ Architecture deep-dive · Three-way merge protocol · Engineering specs

Status

v1.0.10 tagged. Closes the two TypeScript SDK gaps the v1.0.9 retest flagged. CLI, Python SDK, and TypeScript SDK now all go through the same scrub regex and the same HMAC-chained pf_effects::Ledger::append code path — full parity across all three surfaces. Concretely: snapshotFilesystem(store, kind, root, env, messages, opts?) applies the default secret-shaped scrub regex (so JS callers passing { OPENAI_API_KEY: "..." } get safe-by-default redaction), and opts.effects = [...] routes every tool call through the HMAC chain (was previously a hardcoded empty blob regardless of input — TS integrations had no ACRFence protection at all). New readBlob SDK surface to mirror the Python read_blob. The smoke-test bug that hid the leak (new Map(...) silently serialized to {} over napi) is fixed and replaced with 3 regression tests proving the exact attack patterns the auditor reported. cargo deny check: advisories ok, bans ok, licenses ok, sources ok. Earlier rounds' fixes still apply (CLI scrub + ledger, Python SDK scrub + ledger, vLLM/SGLang persistence, cargo-audit clear).

metric	observed	target
Snapshot p50, synthetic 4-layer fixture (macOS arm64)	7.9 ms	< 500 ms p99
Snapshot p50, real GPU host (Modal A10G, 64 × 4 KiB)	42 ms (warm)	< 500 ms p99
Bit-exact KV-cache replay, vLLM 0.6.6 + TinyLlama-1.1B on A10G	✅ verified — 38 619 KV pages snapshotted, restored, regenerated text byte-identical	out_a == out_b
Cache capture, 64 pages	531 µs	—
12-fork ÷ 1-fork storage ratio	well < 1.5×	≤ 1.5×
Total tests passing	200	—

Synthetic-fixture numbers come from cargo bench --workspace. GPU numbers come from modal run scripts/gpu-validate-modal.py; raw JSON lives in benchmarks/gpu-validation/ and the breakdown in benchmarks/RESULTS.md. vLLM ≥0.10 (V1 engine, subprocess-worker architecture) is the v1.0.2 milestone — the v1.0.1 adapter targets V0's directly-introspectable CacheEngine.

Install

cargo install processfork                          # Rust CLI (the `pf` binary)
pip   install processfork                          # Python SDK
npm   install @processfork/sdk                     # TypeScript SDK

Per-adapter packages (one each on PyPI):

pip install processfork-claude-code
pip install processfork-langgraph
pip install processfork-openinterpreter
pip install "processfork-vllm[vllm]"               # needs CUDA + vllm ≥ 0.10
pip install "processfork-sglang[sglang]"           # needs CUDA + sglang ≥ 0.5
pip install "processfork-autogen[autogen]"
pip install "processfork-crewai[crewai]"

Build from source if you want to hack on it:

git clone https://github.com/manav8498/processfork && cd processfork
cargo build --release -p processfork               # → target/release/pf

Full build-from-source instructions in docs/install.md. Pre-built wheels cover macOS arm64, Linux x86_64, and Linux aarch64; macOS Intel + Windows wheels arrive in v1.0.1 (operator: same package, just more platforms).

Repo layout

crates/      Rust workspace (10 crates: pf-core, pf-cache, pf-world, pf-effects,
             pf-model, pf-merge, pf-registry, processfork (CLI, the `pf` binary), pf-py, pf-ts)
adapters/    7 first-party integration packages
benchmarks/  PFBench harness + Criterion microbench
docs/        mdBook source (25+ pages)
examples/    8 self-contained runnable examples
demo/        60-second demo recording script

Docs

Your first fork (5 min) · 60-second demo · Architecture · Merge protocol · Security model · Performance tuning · Engineering specs

Contributing

PRs welcome. The bar is cargo fmt, cargo clippy --all-targets -- -D warnings, cargo test --workspace, plus a green coverage delta. See CONTRIBUTING.md.

License

MIT.