WorktreeProof
Open source · agent-ready

Vibe fast.
Ship with proof.

WorktreeProof is open-source vibe coding guardrails for AI coding agents: a small, local-first toolkit that keeps work scoped, changes inspectable, and every finished lane backed by a clear receipt.

View the source Try the install path

Apache-2.0 · Node.js 20+ · zero runtime dependencies

scope before speedevidence over vibesclose the loop
01 / The loop

A proof pipeline
for the messy middle.

Agents move quickly when the boundaries are explicit. WorktreeProof gives a lane a beginning, a safe working surface, and a verifiable end.

  1. 01

    Plan the lane

    Turn a request into one named scope, target check, and owner-visible intent.

  2. 02

    Reserve the surface

    Keep parallel work apart with conflict-aware reservations and disposable worktrees.

  3. 03

    Run the checks

    Capture commands, test output, UI review notes, and the context needed to repeat them.

  4. 04

    Close with a receipt

    Ship a redacted record that says what changed, what passed, and what remains.

02 / Built for agents

Guardrails that
stay out of the way.

Use the pieces you need, from a single local command to a coordinated set of agent lanes.

Skills

Plain Agent Skills bring the same scope-and-proof habits to compatible coding agents.

portable prompts

Safe delegation

Give each lane a unique identity and non-overlapping file scope before it starts.

explicit ownership

Worktrees

Use clean, temporary working surfaces so parallel edits do not quietly collide.

isolated by default

Tools

Choose the smallest local or connected capability that can complete the next step.

capability-aware

UI review

Keep visual checks in the receipt, alongside keyboard and responsive evidence.

screen to proof

Best practices

Use focused checks and one clear terminal disposition instead of ceremonial status.

quality with intent

Token & resource efficiency

Keep context bounded, reuse receipts, and avoid retries that add noise without progress.

less waste

Receipts

Leave a compact, redacted record that another person or agent can inspect later.

closure you can read

Codex + Claude bridge

Exchange bounded local task and result messages without launching either assistant or sharing hidden context.

explicit handoff

Task awareness

See redacted host-reported task status and mode while raw IDs, titles, prompts, and paths stay out.

reported, never inferred
03 / Starter recipes

Start small.
Keep the trail.

These are patterns, not a new ceremony. Pick a recipe, adapt the scope, and let the receipt carry the context forward.

RECIPE / 01

Triage a bug

Reserve the failing area, reproduce once, and attach the focused test that proves the fix.

worktree-proof plan bug-fix --scope src/See the command path
RECIPE / 02

Review a UI

Pair a visual pass with keyboard and viewport notes before the lane closes.

worktree-proof run ui -- npm testSee the command path
RECIPE / 03

Close a release

Collect checks and redacted evidence, then make the terminal disposition explicit.

worktree-proof close release --receipt proof.jsonSee the command path
04 / Try it locally

A clean start is
one command away.

WorktreeProof is designed to be inspected before it is adopted. Install the tagged GitHub release, run the local doctor, and keep every write explicit.

Read the install notes
terminal
$ npm install --global github:Nedal7707/worktree-proof#v0.4.0
$ worktree-proof doctor
$ worktree-proof resources scan --json

✓ local diagnostics ready — inspect before writing
05 / Privacy by shape

Local-first,
plain about limits.

WorktreeProof keeps its state in the project you run it in. The toolkit has no runtime dependencies and no built-in telemetry by default; inspect the source and choose your own integrations.

Use ordinary care with command output and receipts: keep private values out of both.

Non-claims

What this page does not promise

  • Not a replacement for human review, release ownership, or your security process.
  • Not a guarantee that an agent will make the right change.
  • Not affiliated with, endorsed by, or sponsored by a model vendor.
  • No claims about users, stars, downloads, or being the best tool.
06 / Questions

Good questions
make better receipts.

A few straight answers before you open the repo.

What is WorktreeProof?

WorktreeProof is an open-source toolkit for scoped AI coding-agent work. It helps teams reserve non-overlapping lanes, run checks, and record a closure receipt.

Does it replace code review?

No. It makes the scope, checks, and evidence easier to inspect; your normal review and release decisions still matter.

Where does it run?

The current project is a JavaScript and Node.js toolkit that can be run from a local checkout. It has no runtime dependencies.

Can I use it with my agent?

The core workflow is local and model-agnostic. The repository also includes plain Agent Skills and adapters that you can inspect and adapt.

07 / Open by design

Bring a sharper
way to close.

Read the docs, try a recipe, and send a focused change. Small improvements to schemas, skills, adapters, and examples are welcome.

Read contributing notes