Using git worktrees to parallelize AI coding

As a continuation of the earlier post that introduced workmux, here's a useful pattern for delegating tasks to worktree agents.

#The workflow in a nutshell

The workflow uses a main agent on the main branch to brainstorm and dispatch tasks, while worktree agents run in separate worktrees.

1. Brainstorm tasks with the main agent
2. Refine the items, by yourself or with the help of the agent
3. Delegate tasks to worktree agents
4. Review changes and merge into main branch as they finish

The steps don't have to happen in strict sequence. You can dispatch one task, refine the next while it runs, and review changes as they come in.

#Step 1: Come up with tasks

The first step is to come up with things to do. The tasks can be anything: features, bug fixes, general improvement ideas or refactoring suggestions etc. As an example, I'll ask the agent for improvement ideas for a project I happen to be working on, but you could just as easily use a to-do list file as a source for the tasks.

I work with Claude Code in my main tmux window, which acts as a coordinator that will later delegate tasks to worktree agents. This agent stays on the main branch, brainstorms ideas, writes prompts, and spawns worker agents in their own worktrees.

> Ask Gemini for ideas on how to improve the bot. Write the ideas to a markdown
  file with as much detail as possible.

⏺ I'll first explore the codebase to understand what this bot does, then consult
  Gemini with relevant context.

⏺ Explore(Explore telegram-tori-bot codebase)
  ⎿  Done (29 tool uses · 48.6k tokens · 57s)

⏺ Now I have a good understanding of the codebase. Let me consult Gemini with
  the key files for improvement ideas.

⏺ consult-llm - consult_llm (MCP)(prompt: "I have a Telegram bot that...",
                                  model: "gemini-3-pro-preview", ...)
  ⎿  Here is a comprehensive analysis of your Telegram bot codebase with
     actionable improvement suggestions.
     … +186 lines (ctrl+o to expand)

⏺ Excellent! I received comprehensive improvement ideas from Gemini. Let me
  write these to a detailed markdown file.

⏺ Write(IMPROVEMENT_IDEAS.md)
  ⎿  Wrote 730 lines to IMPROVEMENT_IDEAS.md
     # Telegram Tori Bot - Improvement Ideas
     *Generated via Gemini analysis on 2025-12-29*
     This document contains comprehensive improvement suggestions for the
     Telegram Tori bot, organized by priority and category.
     ---
     ## Table of Contents
     … +720 lines (ctrl+o to expand)

I like to occasionally use gemini-3-pro-preview through consult-llm-mcp to see what Gemini comes up with.

#Step 2: Refine the tasks

Gemini came up with a nice list of items to do, but I don't necessarily want to implement all of them, or they might require some adjustments. The advantage of a markdown file as an intermediate step, as opposed to just holding the items in the agent's context, is that you can freely edit it in the editor. However, either way works, so this step is optional.

#Step 3: Delegate to an agent in a worktree

As mentioned in the introductory post, the advantage of worktrees in agent parallelization is that the changes done won't conflict with other agents. Agents will only see type errors, test failures, or lint issues caused by their own changes, and reviewing their work is also much easier.

From Gemini's suggestions, I want to implement the natural language editing feature, which lets users edit draft listings with messages like "Set price to 80€". (What a great idea by the way. This avoids the need to build a separate bot slash command for every conceivable action.)

Instructing the agent to create a worktree for a task with workmux requires some prompt glue, so I have a custom command that makes worktree creation easy.

Launch one or more tasks in new git worktrees using workmux.

Tasks: $ARGUMENTS

## Instructions

Note: The tasks above may reference something discussed earlier in the
conversation (e.g., "do option 2", "implement the fix we discussed"). Include
all relevant context from the conversation in each prompt you write.

If tasks reference a markdown file (e.g., a plan or spec), re-read the file to
ensure you have the latest version before writing prompts.

For each task:

1. Generate a short, descriptive worktree name (2-4 words, kebab-case)
2. Write a detailed implementation prompt to a temp file
3. Run `workmux add <worktree-name> -b -P <temp-file>` to create the worktree

The prompt file should:

- Include the full task description
- Use RELATIVE paths only (never absolute paths, since each worktree has its own
  root directory)
- Be specific about what the agent should accomplish
- Include instruction to review the changes with Gemini after completing the
  task (use `mcp__consult-llm__consult_llm` with model "gemini-3-pro-preview",
  include relevant files and git_diff)

## Workflow

Write ALL temp files first, THEN run all workmux commands.

Step 1 - Write all prompt files (in parallel):

```bash
tmpfile=$(mktemp).md
cat > "$tmpfile" << 'EOF'
Implement feature X...
EOF
echo "$tmpfile"  ```

Step 2 - After ALL files are written, run workmux commands (in parallel):

```bash
workmux add feature-x -b -P /tmp/tmp.abc123.md
workmux add feature-y -b -P /tmp/tmp.def456.md
```

After creating the worktrees, inform the user which branches were created.

This command instructs the agent to create a new worktree with workmux, passing the referenced task as a prompt to the agent that starts within the created worktree and its tmux window.

> /worktree Implement natural language editing

⏺ Bash(tmpfile=$(mktemp).md && cat > "$tmpfile" << 'EOF'…)
  ⎿  /tmp/tmp.43Qi9kRtoS.md

⏺ Bash(workmux add natural-language-edit -b -P /tmp/tmp.43Qi9kRtoS.md)
  ⎿  Running setup commands...
     ✓ Setup complete
     ✓ Successfully created worktree and tmux window for 'natural-language-edit'

⏺ Created worktree natural-language-edit on branch natural-language-edit.
  The agent is now implementing the natural language editing feature.

> /worktree Fix the listing_handler.go race condition

⏺ Bash(tmpfile=$(mktemp).md && cat > "$tmpfile" << 'EOF'…)
  ⎿  /tmp/tmp.JNGvRIz4NC.md

⏺ Bash(workmux add fix-race-condition -b -P /tmp/tmp.JNGvRIz4NC.md)
  ⎿  Running setup commands...
     ✓ Setup complete
     ✓ Successfully created worktree and tmux window for 'fix-race-condition'

⏺ Created worktree fix-race-condition on branch fix-race-condition.
  The agent is now working on fixing the nil draft race condition.

Because every worktree has its own tmux window with the agent process running, you can interact with the agent as needed, or start reviewing the changes as they come in.

#Step 4: Review changes and merge

Once an agent finishes, you can switch to its window and review the changes like you normally would with git diff or other tools. I usually skim the diff in Neovim and request changes as needed. For the natural language editing feature, it's useful to also run the dev server in another pane to test the changes manually.

You may have noticed the /worktree command asks agents to review the changes before finishing. I find it extremely useful to do a round of review with AI, and especially Gemini, before looking at the diff myself.

When happy with the changes, commit (or have the agent do it), then run workmux merge --rebase to rebase on main, merge, and clean up the worktree.

To minimize conflicts, I try to organize work so that parallel agents work on separate areas of the codebase. For example, better avoid having one agent refactor a module while another adds features to it. However, if there are conflicts from other agents' merged branches, the worktree's agent can usually resolve them (see earlier post).

Read next My setup, and why tmux workflow is better than ever for more on the tmux workflow these tools are built around.