wtcraft

Git-native agent governance core.

>

wtcraft is a lightweight governance core for worktree-based agent workflows. It defines task contracts, tracks lifecycle state, and exposes deterministic scope and verification checks for CLIs, agents, and graphical clients.

<p align="center"> <img src="https://raw.githubusercontent.com/zywkloo/wtcraft/main/wtcraft-icon.PNG" alt="wtcraft icon" width="120" /> </p>

Install

pipx install wtcraft       # pip / pipx (recommended — isolated venv)
npm install -g wtcraft     # npm (global)
brew tap zywkloo/wtcraft https://github.com/zywkloo/wtcraft && brew install wtcraft

Short alias available after install: wtc

Quick Start

wtcraft --version                        # print the installed CLI version
wtcraft init                            # scaffold harness into current repo
wtcraft init --local                    # scaffold locally; ignore via .git/info/exclude
wtcraft patch                           # append routing stubs to CLAUDE.md / AGENTS.md
wtcraft lang install --lang zh-CN       # enforce output language in CLAUDE.md
wtcraft new feat/my-task                # create worktree + task contract
wtcraft new --base origin/main feat/x   # override the base branch/ref explicitly
wtcraft status                          # list active worktree contracts
wtcraft capabilities --json             # discover machine-protocol features
wtcraft status --json --repo /repo      # machine-readable status for a target repo
wtcraft check <worktree-name-or-path>   # verify Scope / Off-limits
wtcraft verify <worktree-name-or-path>  # run Verification commands

wtcraft new resolves its base in this order: --base, then WTCRAFT_BASE_BRANCH, then origin/HEAD, then local main, local master, local develop, and finally the current branch.

After running wtcraft init, you can use these slash commands in Claude Code:

• /planwt <task description>: Plan task + create worktree
• /finishwt <worktree-name>: Run verification and finish
• /statuswt: List active worktree task files

The Layered Agent Team

<!-- wtcraft:models:start -->

• Orchestrator (e.g., Gemini 3.5 Flash): Sits at the top of the workflow. Highly tool-agentic, low-latency, and coordinates the overall project state. It focuses on environment orchestration, git logistics, verification suites, and telemetry. Core features like cross-repository worktree monitoring, automated session summarization, and active agent handoff routing are coming soon (upcoming role integration).

• Planner (e.g., Claude Opus 4.8): The slow, high-reasoning "architect". It reads the requirement, analyzes the code context, and designs the bounded execution contract (.worktree-task.md) specifying Scope, Off-limits, and Verification steps.

• Executor (e.g., GPT-5.4): The precision coder. It is budget-friendly, highly focused, and operates strictly inside the isolated worktree sandbox, adhering strictly to the contract boundaries.

• Verifier (e.g., Claude Opus Fable 5): The quality gatekeeper. It automatically conducts code reviews, checks for style/security constraints, and runs PR-level checks. If verification fails, it can trigger a feedback loop back to the Planner or Executor.

• Finisher (e.g., Gemini Flash 3.5): Performs deterministic boundary validation (wtcraft check), test suite verification (wtcraft verify), and cleans up local worktree assets after a successful merge to keep the development disk clean. Additionally, in an upcoming release (integrating with PR #12), the Finisher will aggregate and report token telemetry to track cost, budget, and API usage per agent model (Coming Soon).

<!-- wtcraft:models:end -->

Commands

Why

AI agents (and human contributors) hallucinate, over-engineer, and accidentally break unrelated code. While parallel agents are useful, raw parallelism creates common problems: unclear handoffs, context pollution, and file collisions.

wtcraft provides a definitive safety harness. It focuses on handoff, boundaries, and deterministic containment, not just concurrency.

• Git-Native Containment: Keep agent work physically isolated with git worktree.
• Task Contracts: Make agent handoffs explicit with a per-task whitelist in .worktree-task.md.
• Deterministic Gating: Enforce scope boundaries at the commit/PR level. If a task isn't in scope, the code doesn't merge.
• Budget-Aware: Avoid infinite LLM loops and track API usage per worktree.

No hosted platform is required. No custom runtime is required. You can use Aider, Cursor, Claude, or Devin — wtcraft simply wraps your working directory in a zero-trust governance layer.

Docs

• Protocol Contracts
• Rust Core Extraction ADR
• Roadmap
• Gotchas & Coding Survival Guide
• Principles
• Migration Notes
• Changelog

Testing

bash tests/run_all.sh

License

Apache-2.0. See LICENSE.