Getting Started

Willow is a git worktree manager built for AI agent workflows. It gives every task its own isolated directory via git worktrees, then adds fzf-based switching and live agent status tracking on top.

<willow-base> defaults to ~/.willow. You can change it with WILLOW_BASE_DIR, the global baseDir config, or ww migrate-base <path>.

Install

Homebrew

brew install iamrajjoshi/tap/willow

From source

go install github.com/iamrajjoshi/willow/cmd/willow@latest

Requirements

  • git
  • tmux — optional, for the ww tmux picker popup
  • gh — optional, required for ww new --pr and ww stack status

fzf is compiled into the willow binary, so no separate install is needed.

Add to your .bashrc / .zshrc:

eval "$(willow shell-init)"

For fish:

willow shell-init | source

This gives you the ww alias and helper commands:

CommandDescription
ww <cmd>Alias for willow
ww swfzf worktree switcher (cd's into selection)
wwn <branch>Create worktree + cd into it
wwwcd to <willow-base>/worktrees/

Terminal tab titles (optional)

Set terminal tab title to the current worktree name:

eval "$(willow shell-init --tab-title)"

Each tab shows repo/branch (e.g. myrepo/auth-refactor) when inside a willow worktree.

All examples below use ww, which is the shell alias for willow. If you skipped shell integration, replace ww with willow in all commands.

Claude Code skill

Willow ships a Claude Code skill at skills/willow/ that teaches Claude when to reach for ww commands. Once installed, Claude uses ww checkout, ww sync, ww dispatch, and the rest automatically whenever you ask it to work on branches, PRs, or parallel tasks.

Install with the skills CLI:

# Global — available across all projects
npx skills add iamrajjoshi/willow --skill willow -g -a claude-code
 
# Project-local — only inside the current project
npx skills add iamrajjoshi/willow --skill willow -a claude-code

What the flags do:

  • -g installs to ~/.claude/skills/ instead of the current project's .claude/skills/.
  • -a claude-code targets Claude Code. The CLI supports other agents too — see npx skills add --help.
  • --skill willow picks just the willow skill. Without it, the CLI prompts for each skill in the repo.

Alternatively, clone the repo into your skills directory:

git clone https://github.com/iamrajjoshi/willow ~/.claude/skills/willow

The skill is non-invocable by design (user_invocable: false) — Claude auto-triggers it when it sees worktree, branch, or PR intent in a prompt.

Claude Code status tracking

ww cc-setup

Installs hooks into ~/.claude/settings.json that write per-session agent status (BUSY / DONE / WAIT / IDLE) to <willow-base>/status/. Supports multiple Claude sessions per worktree. This powers the status column in ww ls, ww sw, ww status, and ww dashboard.

Quick start

# Clone a repo (one-time)
ww clone git@github.com:org/myrepo.git
 
# Create a worktree and cd into it
wwn auth-refactor
 
# Start Claude Code
claude
 
# In another terminal — create a second worktree
wwn payments-fix
claude
 
# Switch between worktrees (fzf picker with agent status)
ww sw
 
# Check on all agents
ww status
 
# Live dashboard across all repos
ww dashboard
 
# Clean up when done
ww rm auth-refactor

Tmux integration

If you use tmux, willow can manage sessions per worktree with a popup picker:

ww tmux install    # prints tmux.conf lines to add

Then prefix + w opens a popup with all worktrees, live Claude output preview, and status colors. See Tmux Integration for full details.

Terminal setup

Recommended Ghostty layout per worktree:

┌─────────────────────────────────────┐
│ Tab: myrepo/auth-refactor           │
├──────────────────┬──────────────────┤
│  claude          │  claude          │
│  (agent 1)       │  (agent 2)       │
├──────────────────┴──────────────────┤
│  shell (git diff, tests, etc.)      │
└─────────────────────────────────────┘
Commands