Claude Code: Parallel Development with /worktree
Building on my workflow with /todo and /commit, I've created the /worktree command to enable parallel development on multiple tasks using Git worktrees.
This post is part of my Claude Code setup series.
Evolution of My Workflow
I started with a simple pattern: maintain a todo list and repeatedly run three commands:
/todo- Implement one task/commit- Create a commit/compact- Manage the context window
This workflow steadily churned through my todo list, but LLMs can be slow. While waiting for one task to complete, I'd switch to working on a second task. Initially, I tried running Claude on two tasks in the same directory simultaneously, but they would trample each other's changes.
I started using Git worktrees. It worked well. Each instance of Claude works in its own directory, eliminating conflicts, while still working on a single git repository. Later, Anthropic officially recommended using worktrees in their documentation, which validated the approach.
Building the /worktree Command
While Anthropic recommends using worktrees, they don't provide any automation or commands for managing them yet. I found myself spending too much time creating worktrees, copying todo lists, and managing branches myself. That's where my /worktree command comes in.
Using the command
This command can be used within claude, with a number of worktrees to create.
/worktree 3
⏺ 1 worktree has been created so far.
⏺ 2 worktrees have been created so far.
⏺ 3 worktrees have been created.
Even though the worktrees used for parallel work, they are created in serial. Each time a worktree is created, Claude also opens a new iTerm tab, and kicks off the command:
claude --dangerously-skip-permissions /todo
How It Works
The /worktree command automates several key steps:
1. Find and mark the next available todo
- [ ] Implement user authentication with JWT
becomes:
- [>] Implement user authentication with JWT <!-- worktree: implement-user-auth-jwt -->
2. Create the worktree
git worktree add ../my-app-implement-user-auth-jwt -b task/implement-user-auth-jwt HEAD
3. Set up the worktree environment
# Copy environment files if they exist
cp .envrc ../my-app-implement-user-auth-jwt/
direnv allow ../my-app-implement-user-auth-jwt
# Trust the directory for mise
mise trust ../my-app-implement-user-auth-jwt
4. Create a focused todo file
mkdir ../my-app-implement-user-auth-jwt/.llm
echo "- [ ] Implement user authentication with JWT" > .llm/todo.md
5. Launch Claude in a new terminal tab
Launch a new iTerm tab and run:
cd ../my-app-implement-user-auth-jwt
claude --dangerously-skip-permissions /todo
And if we wrote /worktree 3, the command will repeat these steps until 3 worktrees are created.
Integration with /todo Workflow
The /worktree command creates a new worktree with its own .llm/todo.md file containing just the single task. This means you can use the same /todo workflow we've already established, but now with better isolation and the ability to work on multiple tasks in parallel. Each worktree starts fresh from main, giving you a clean context for every task.
Managing Context Size
If we have a large number of tasks we want to run in parallel, we need to be careful about the context size. There are two ways I manage this.
A command like /worktree 10 can run out of context in a single Claude session, trigger auto-compaction, and get lost. To avoid this, I move the looping outside of Claude.
for i in $(seq 1 10); do claude --dangerously-skip-permissions --print /worktree; done
The second problem is that if we run too many tasks in parallel, we can quickly hit API usage limits. To avoid this, I sometimes downgrade the model. At the time of writing, that means switching from Opus 4 to Sonnet 4.
If I'm going step away for a while, I can also use the sleep command to space out the requests. This allows me to run tasks overnight without hitting API limits.
for i in $(seq 1 11); do claude --dangerously-skip-permissions --print /worktree; sleep 1200; done
Finishing Up
After all parallel tasks complete, I cherry-pick the completed work into a single branch. This gives me a chance to review all the changes together and ensure they work well as a cohesive whole.
If there are any merge conflicts, and they look at all tricky to resolve, I just throw away the work and mark the todo as [ ] again.
Finally, I clean up all worktrees except the current one.
git worktree remove ../myproject-add-user-auth-jwt
git branch -d task/add-user-auth-jwt
Or I ask Claude to do it for me. If you ask Claude to clean up worktrees, make sure to tell it not to use --force.
Full /worktree Command
Here's the complete /worktree command that automates the entire process:
---
name: worktree
description: Create a git worktree in a peer directory using the plugin worktree script. Use when the user asks for a new worktree or a branch checked out beside the repo.
---
# Worktree
Resolve `<plugin-root>` before running plugin scripts:
- In Claude Code, use `${CLAUDE_PLUGIN_ROOT}`.
- In Codex, use the plugin root that contains this `skills/worktree/SKILL.md` file.
## Create the Worktree
Use the user's text as the branch name if it is already kebab-case (e.g., `auth-feature`); otherwise derive a short kebab-case name from it. From the repository root, run:
```bash
<plugin-root>/scripts/worktree.sh <branch-name>
```
On failure, stop and summarize the error. On success, report the worktree path.
## Opening a Terminal Tab
Open a terminal tab in the worktree only if the user explicitly asks.
In iTerm:
```bash
osascript -e 'tell application "iTerm"
tell current window
create tab with default profile
tell current tab
tell current session
write text "cd <worktree-absolute-path>"
end tell
end tell
end tell
end tell'
```
In xfce4-terminal:
```bash
xfce4-terminal --tab --working-directory="<worktree-absolute-path>" -x bash -c "cd <worktree-absolute-path>; exec bash"
```