worktree

Armadillo’s native worktree CLI — creates isolated workspaces for parallel AI agent workflows with one-command branch creation, agent launch, merge automation, and cache sharing

Model	Source	Category
sonnet	core	Git

Overview

Trigger	Action
Any feature work	worktree create <branch>
Parallel agent dispatch	worktree launch <branch> "prompt" per agent
Check on parallel work	worktree status or worktree list
Work is done	worktree merge <branch>
Discard work	worktree remove <branch>
Cleanup merged branches	worktree prune

Full Reference

worktree

armadillo’s native worktree management. One command to create a worktree, one to launch an agent, one to merge and clean up. No external dependencies.

Mandatory Announcement — FIRST OUTPUT before anything else:

┏━ 🚀 worktree ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ [one-line description of what worktree work]    ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Quick Reference

Command	What	Example
worktree create <branch>	New worktree + branch from main	worktree create feat/auth
worktree list	All worktrees with status	worktree list
worktree remove <branch>	Remove worktree + branch	worktree remove feat/auth
worktree merge <branch>	Squash merge via PR + cleanup	worktree merge feat/auth
worktree launch <branch> "prompt"	Create + launch claude agent	worktree launch feat/auth "Add OAuth"
worktree status	Overview + running agents	worktree status
worktree prune	Remove merged worktrees	worktree prune

Parallel Agent Workflow

The killer pattern — launch multiple agents in parallel:

worktree launch feat/auth "Add OAuth login with Google" &
worktree launch feat/api "Build REST endpoints" &
worktree launch fix/checkout "Fix null pointer in checkout" &
wait

Each agent gets its own worktree, its own branch, shared deps cache. Zero conflicts.

Monitor with worktree status. Merge winners with worktree merge <branch>.

When to Use

Trigger	Action
Any feature work	worktree create <branch>
Parallel agent dispatch	worktree launch <branch> "prompt" per agent
Check on parallel work	worktree status or worktree list
Work is done	worktree merge <branch>
Discard work	worktree remove <branch>
Cleanup merged branches	worktree prune

Directory Convention

Worktrees live in .claude/worktrees/ (auto-gitignored):

project/
├── .claude/worktrees/
│   ├── feat-auth/        ← branch / → -
│   ├── feat-api/
│   └── fix-checkout/

Cache Sharing

worktree create auto-detects stack and shares caches:

• Node: hard-linked node_modules/ (zero disk overhead)
• Rust: symlinked target/
• Python: symlinked .venv/

Reference

See reference/commands.md for full flag documentation.

Integration

Called by:

• dispatching-parallel-agents — parallel agent launch into worktrees
• executing-plans — isolated workspace before task execution
• subagent-driven-development — isolated workspace before task execution
• armadillo-maker — branch isolation for skill/pack creation

Pairs with:

• finishing-a-development-branch — merge/cleanup after work complete