Vibe fast. Ship with proof.
WorktreeProof provides evidence-backed guardrails for AI coding agents. It helps you describe a small change, reserve a non-overlapping scope, run reviewed commands, and keep a redacted receipt of what was checked. It is local-first, model-agnostic, and intentionally does not claim guaranteed security, correctness, adoption, or autonomous merging.
Use Node.js 20 or newer:
npm install --global github:Nedal7707/worktree-proof#v0.1.0
worktree-proof doctor
worktree-proof plan docs-refresh --scope docs/
worktree-proof reserve docs-refresh --scope docs/
worktree-proof run docs-refresh -- node --version
worktree-proof status --json
worktree-proof release docs-refresh --reason "demo complete"Every mutating action is explicit. --dry-run previews state changes and
init is preview-only unless --apply --confirm are supplied. Commands pass
argv with shell:false; WorktreeProof is not a sandbox.
To use the WorktreeProof Agent Skill with Codex, open the WorktreeProof Stack skill. Codex will ask you to confirm installation; opening the link alone does not install anything.
The same portable skill can be placed in Claude Code's skills directory. Both
clients use the same .worktree-proof/ state and schemas; neither client is
invoked by the other.
- Lane IDs and relative file scopes are normalized and checked for overlap.
- Reservations are serialized with bounded leases and stale-state detection.
- Commands are executed without an implicit shell and output is bounded/redacted.
- Closure receipts are JSON-safe and validate their terminal evidence.
- Tool probes are declarative and probe-only; no installers or arbitrary shell.
- Resource scans are read-only and produce conservative concurrency/cleanup recommendations. Cleanup plans never delete files.
- The Codex↔Claude bridge stores bounded local task/status/result handoffs and reserves non-overlapping task scopes; it never forwards hidden context.
- Task awareness hashes host-provided IDs, discards private task content, and reports a mode only when the host explicitly provides it.
worktree-proof tools list
worktree-proof tools scan --json
worktree-proof tools recommend --goal testing --goal javascript
worktree-proof resources scan --json
worktree-proof resources plan --allowed-root .cache --allowed-root build
worktree-proof recipes list
worktree-proof recipes show docs
worktree-proof init preview --target generic-prompt
worktree-proof bridge inbox --agent codex --json
worktree-proof tasks inspect --input host-snapshot.json --jsoninit apply requires --confirm, refuses collisions and path escapes, and
never overwrites an existing file. resources plan is an inventory only.
The public helper request defaults to 8 and supports an explicit request up to
24, but the host/runtime ceiling and CPU/RAM/disk safety can reduce the
effective value to zero.
skills/— concise, portable Agent Skills.recipes/— bounded examples for common maintenance work.catalog/— declarative tool manifests.schemas/— lane, receipt, recipe, resource, and skill-source contracts.site/— a static, tracker-free overview.
State stays in the project directory and there is no telemetry or runtime dependency. Do not put credentials in command arguments, environment dumps, receipts, or issue reports. Read SECURITY.md and docs/PRIVACY.md before using integrations. WorktreeProof does not authenticate users, replace code review, prove an external deployment, or guarantee that an AI-generated change is safe.
For crash-risk reduction, resources scan and resources plan provide bounded
diagnostics, backpressure recommendations, and recovery-oriented cleanup
inventory. They do not change OS settings, kill processes, delete files, run a
daemon, or promise to prevent crashes. If you inspect a crash dump or
.heapsnapshot, treat it as potentially containing conversations or
credentials and keep it private; this project never uploads or shares it.
Run npm test, npm run check, and the release checklist before proposing a
focused change. See CONTRIBUTING.md,
docs/CROSS-AGENT-COMPATIBILITY.md,
docs/BRIDGE.md,
docs/TASK-AWARENESS.md, and
docs/RELEASE-CHECKLIST.md.
WorktreeProof is an unofficial community project and is not affiliated with, endorsed by, or sponsored by any vendor. It is released under the Apache License 2.0.