wtcraft 0.3.0

Craft bounded multi-agent workflows with git-native worktrees

wtcraft - Worktree Craft

npm install -g wtcraft

wtcraft is a lightweight, git-native harness for solo developers orchestrating multiple coding agents on a limited budget.

Keywords: Solo Dev · Budget-Aware · Agent Handoff · Boundaries · Lightweight

The goal is simple:

• keep agent work isolated with git worktree
• make agent handoffs explicit with a task contract
• keep file and task boundaries easy to verify
• stay usable from CLI + any IDE

No hosted platform is required. No custom runtime is required.

Why

Parallel agents are useful, but raw parallelism creates four common problems:

• unclear handoff between planner and executor agents
• context pollution across tasks
• file ownership collisions
• review overload from too many noisy PRs

wtcraft focuses on handoff, boundaries, and budget-aware sequencing, not maximum concurrency.

For the design story behind this project, read: Beyond Worktrees: A Budget-Aware Multi-Agent Coding Harness for Solo Developers.

Core Model

1. Planner defines a bounded task contract.
2. Executor works only inside that contract.
3. Verifier checks scope, off-limits, and completion gates.
4. Finisher handles push/PR/cleanup.

This supports a DAG workflow:

• merge shared foundation tasks first
• run file-disjoint tasks in parallel
• serialize tasks that touch shared files

Project Status

Early public bootstrap.

Current scope:

• open documentation for workflow and roadmap
• starter contract and command specs
• CLI MVP available (init, status, check)

Requirements

Dependency	Required	Notes
bash	yes	macOS / Linux
git	yes	worktree support (git ≥ 2.5)
Claude Code CLI	no	optional planner / finisher agent
Codex CLI	no	optional executor agent
Node.js / npm	no	only needed for npm install distribution

Claude Code and Codex are agent tools that use wtcraft — they are not prerequisites for the CLI itself.

Install

npm (global):

npm install -g wtcraft

pip / pipx:

pipx install wtcraft        # recommended — isolated venv, no conflicts
# or
pip install --user wtcraft

Homebrew (tap):

brew tap zywkloo/wtcraft https://github.com/zywkloo/wtcraft
brew install wtcraft

From source (no package manager needed):

git clone https://github.com/zywkloo/wtcraft.git
chmod +x wtcraft/scripts/wtcraft
# add wtcraft/scripts to PATH, or run directly:
wtcraft/scripts/wtcraft init

Quick Start

wtcraft init                            # scaffold harness into current repo
wtcraft init --patch-agent-files        # also append routing stubs to CLAUDE.md / AGENTS.md
wtcraft new feat/my-task                # create worktree + task contract
wtcraft status                          # list active worktree contracts
wtcraft check <worktree-name-or-path>   # verify Scope / Off-limits
wtcraft verify <worktree-name-or-path>  # run Verification commands
wtcraft help [command]                  # per-command usage

What init scaffolds:

• .agent-harness/planner.md
• .agent-harness/executor.md
• .agent-harness/finisher.md
• .claude/commands/planwt.md
• .claude/commands/finishwt.md
• .worktree-task.template.md

init is non-destructive: existing files are not overwritten. By default init does not modify CLAUDE.md or AGENTS.md. Use --patch-agent-files to append managed routing stubs to existing files.

new defaults to base branch develop. Set WTCRAFT_BASE_BRANCH=main (or another branch) when needed.

Docs

• Roadmap
• Principles
• Migration Notes
• Changelog

Testing

chmod +x tests/smoke.sh
tests/smoke.sh

License

Apache-2.0. See LICENSE.