AI coding agents (Codex, Claude Code, Cursor) are incredibly fast, but opaque. They make changes, run tests, maybe pass — but there's no structured, verifiable trail of what they did, what scope they touched, and what actually passed.
WorktreeProof is a local-first guardrail layer you wrap around any AI coding agent. It enforces an evidence-backed loop:
plan → reserve → run → close
- Plan — one named lane, explicit file scope, named acceptance gate.
- Reserve — isolated Git worktree, conflict check, bounded lease.
- Run — your argv (no shell), bounded/redacted output.
- Close — validates a caller-supplied JSON receipt against the closure schema. No evidence = no close.
No cloud, no account, no telemetry, zero runtime dependencies.
What makes it different
- Immutable task contracts — frozen before the first mutation.
- SAFE-3 circuit breaker — freezes at 40 calls / 0 closures.
-
Fixed terminal ledger — progress =
terminal_closed / terminal_totalonly. - Clean architecture — proof domain independent of Git/shell/browser adapters.
-
Fail-closed CLI —
runwithout a reservation →ERR_PROTOCOL. - Portable Agent Skills — same state works with Codex and Claude Code; plus 5 OpenCode plugins (54 tools) and /goal /plan /task /review commands.
Release discipline
v0.4.0 is published with SBOM (CycloneDX), SHA256SUMS, release manifest, npm provenance, and green CI (Node 20/22 x ubuntu/windows, CodeQL, dependency review, Pages). Clean-install verified on Node 20/22/24.
Try it
npm install --global github:Nedal7707/worktree-proof#v0.4.0
Or clone and run install.bat / npm run setup — one-click install for any agentic app: 286 skills, 54 tools, MCP wiring, and a complete gap-free workflow.
Repo: https://github.com/Nedal7707/worktree-proof
Docs: https://nedal7707.github.io/worktree-proof/
npm: https://www.npmjs.com/package/worktree-proof
Apache-2.0, local-first, honest status: new project, 0 stars — but the engineering is the product.
