Worktree Flow: A Guide to Efficient Parallel Development with Claude Code

In modern software development, managing complex codebases and handling multiple parallel development tasks efficiently remains a significant challenge for teams and individual developers alike. This is especially true when leveraging AI-assisted programming tools like Claude Code. How can multiple AI instances handle different tasks simultaneously without interfering with each other or causing code conflicts?

Worktree Flow is designed specifically to solve this bottleneck. It is an orchestration tool based on the Git Worktree mechanism, tailored for managing parallel Claude Code development workflows. Through automated task decomposition, intelligent conflict detection, and structured merging workflows, it allows multiple development tasks to proceed safely and efficiently within the same codebase.

This guide will delve into the core principles, installation methods, usage instructions, and architectural design of Worktree Flow, helping you master this powerful tool for boosting development efficiency.

What is Worktree Flow?

The core philosophy of Worktree Flow is “isolation and coordination.” It allows us to create multiple independent working directories within a single Git repository, with each directory corresponding to a separate development task. This mechanism enables multiple Claude Code instances to work simultaneously in their own isolated environments, handling different functional requirements without overwriting code or causing version confusion.

To achieve this, Worktree Flow defines two distinct operating modes:

1. Coordinator Mode: Acting as the “brain,” this mode analyzes complex user requirements, breaks them down into independent sub-tasks, and plans isolated development environments for each. It assesses potential code conflict risks, formulates implementation plans, and creates the corresponding Git Worktrees.
2. Executor Mode: Acting as the “hands,” this mode automatically activates when a developer enters a specific task environment. It follows the implementation plan laid out by the coordinator to execute specific coding tasks and adheres to strict protocols for committing code and merging back into the main branch.

This dual-mode architecture maximizes parallel development efficiency through atomic locking, conflict detection, and fast-forward merges, while simultaneously ensuring code integrity and a clean commit history.

How Worktree Flow Works

The best way to understand Worktree Flow is to follow a complete development lifecycle, which can be divided into the “Coordinator Workflow” and the “Executor Workflow.”

Coordinator Workflow: From Requirements to Environment

When you have a complex feature to develop, you start by launching the Coordinator Mode in the main branch. This process is not just a simple split; it is a rigorous logical deduction:

1. Task Decomposition
   The coordinator first deeply analyzes your requirements. It doesn’t just cut the task arbitrarily; instead, it breaks down the large task into several independent sub-tasks based on functional boundaries, code hierarchy, and file isolation principles. For example, for a large requirement involving “internationalization” and “payment integration,” the coordinator might break it down into independent tasks like “Add i18n support,” “Integrate Fastlane,” and “Integrate RevenueCat.”

2. Conflict Assessment
   After breaking down the tasks, the coordinator generates a “File Overlap Matrix.” This is a critical step. It analyzes which files different sub-tasks might modify and marks conflict risk levels (HIGH/MEDIUM/LOW). Based on this assessment, the coordinator recommends an optimal task merging order to minimize future merge conflicts.

3. User Confirmation
   Before taking physical action, the coordinator presents you with a detailed plan. This plan includes the task list, potential risk warnings, and the recommended execution order. You must review and approve this plan for the process to continue.

4. Session Initialization
   Once the plan is approved, the system creates a state directory named .worktree-flow/ in the root of the main repository. Inside this directory, a subdirectory named after the Session ID (format usually YYYYMMDD-<summary-slug>) is created for the current development session. This stores session.json (session metadata) and status.json (status tracking files) for each sub-task.

5. Create Worktree
   This is the substantive environment preparation step. The system uses Git’s worktree functionality to create an independent working directory for each sub-task. These directories are typically located at the same level as the main project, following the naming convention ../<project-name>-wt-<task-slug>/. The corresponding Git branches follow the naming convention wt/YYYYMMDD/<task-slug> to distinguish them from regular branches.

6. Distribute Plan
   Inside each newly created worktree, a .worktree-flow-command.md file is automatically generated. This file contains the detailed specifications, boundary constraints, and specific implementation instructions for that task, serving as the core basis for the Executor Mode.

7. Command Setup
   To facilitate operations, the system copies a series of slash command templates to the .claude/commands/ directory of each worktree and the main repository. This allows developers to invoke specific commands directly in different environments to manage the workflow.

Executor Workflow: From Environment to Code

Once the environment is ready, you can enter a specific worktree to start development. At this point, the Executor Mode takes over:

1. Auto-Activation
   When you start Claude Code in a worktree that contains the .worktree-flow-command.md file, the Executor Mode automatically detects and activates. It parses the task metadata from the file and updates the current task’s status to in_progress.

2. Task Execution
   Claude Code strictly follows the implementation instructions outlined in the plan to conduct development. Crucially, it is designed to respect scope boundaries and constantly monitor high-risk areas marked during the conflict assessment, ensuring it does not modify files outside the scope of the task.

3. Commit Protocol
   During development, you need to commit code in a structured way. Worktree Flow provides a dedicated /wt-commit command. This command not only stages and commits current modifications but also generates compliant commit messages. specifically, for the first commit of a task, the system embeds the full task specification into the commit message, creating a permanent audit trail.

4. Merge Back to Base Branch
   When the task is complete, use the /wt-done command. This triggers a rigorous sequence of operations: first, it acquires a global lock to prevent concurrent merges; then it rebases the current branch onto the base branch (usually the latest main branch); next, it merges using the --ff-only parameter (fast-forward only); finally, it releases the lock. This process ensures a linear, clean Git history.

5. Status Tracking
   At any time, you can use the /wt-status command to check the progress of the current task or see the completion status of other tasks in the overall session.

How to Install Worktree Flow

The installation process is straightforward, and you can choose one of the following two methods.

Method 1: Install from Packaged Skill (Recommended)

This is the most hassle-free installation method, suitable for most users.

# 1. Download the worktree-flow.zip archive from the project's releases page.
# 2. Unzip the archive into the Claude Code skills directory.
unzip worktree-flow.zip -d ~/.claude/skills/

Method 2: Install from Source

If you wish to participate in development or need to use the latest source code version, you can choose this method.

# 1. Clone or copy the skills directory to your local machine
cp -r skills/worktree-flow ~/.claude/skills/

# 2. (Optional) If you are in a development environment, you can create a symbolic link
ln -s /path/to/claude-kit/skills/worktree-flow ~/.claude/skills/worktree-flow

After installation is complete, please be sure to restart Claude Code so that the system can correctly load the Worktree Flow skill.

How to Use Worktree Flow

Activating Coordinator Mode

Coordinator Mode is typically launched in the main working directory. You can activate it using any of the following methods:

• Using Slash Command:

  /worktree-flow
  

• Using Natural Language Descriptions:
  You can simply tell Claude your intent directly, for example:

  • “Break this task down for parallel development”
  • “Create worktrees for parallel work”
  • “Handle multiple features simultaneously”

Claude will recognize your intent and initiate the coordinator process, guiding you through the subsequent steps.

Activating Executor Mode

Activating Executor Mode is fully automatic. You do not need to enter any commands manually. As long as you start Claude Code in a worktree whose root directory contains the .worktree-flow-command.md file, the system will automatically recognize it and enter Executor Mode.

Core Command Reference

Worktree Flow provides a structured system of commands, divided into Coordinator Commands and Executor Commands.

Coordinator Commands (Used in the Base Worktree)

These commands are used to manage the lifecycle of the entire parallel development session.

Executor Commands (Used in Task Worktrees)

These commands are used for operations during the specific task development process.

Deep Dive into Architecture Design

The efficient operation of Worktree Flow is built upon several key design decisions. Understanding these architectural details helps you better utilize the tool and troubleshoot issues.

1. Atomic Locking Mechanism

In multi-person or multi-task parallel development, merge conflicts are a major risk. Worktree Flow uses a simple yet effective “atomic locking” strategy.

It utilizes the file system’s mkdir (create directory) operation as an atomic primitive. When a task is ready to merge, the system attempts to create a .worktree-flow/<session-id>/lock.d/ directory. If the directory creation succeeds, it means the lock has been acquired; if the directory already exists, it indicates another task is merging, and the current task must wait. The lock directory contains an owner file to identify the lock holder, preventing deadlocks.

2. Fast-Forward Only Merge

To ensure the Git history remains clear and linear, Worktree Flow enforces “fast-forward only” merging. Before merging back into the base branch, the executor first rebases the current branch onto the latest base branch. This means all commits are based on the most recent code, and the final merge is simply a pointer movement (Fast-forward), avoiding extra merge commit nodes and making history extremely easy to read and revert.

3. Shared Git State

All working directories created via Git Worktree actually share the same Git repository ($GIT_COMMON_DIR). This means branches or commits created in one worktree are immediately visible in all other worktrees. This mechanism allows the coordinator to monitor the branch status of all sub-tasks at any time and facilitates collaboration between tasks.

4. Git Exclude Rules

Worktree Flow automatically adds rules to the shared Git configuration file info/exclude. This ensures that the .worktree-flow/ directory and .worktree-flow-command.md files are not committed to any branch in the codebase. These files are for process management only and should not become part of the project code.

5. First Commit Protocol

To ensure task context information is not lost, Worktree Flow stipulates that the first commit of each task branch must be handled specially. The system embeds the full content of .worktree-flow-command.md into that commit message. This way, even if the task file is deleted in the future, we can still query the full requirements and specifications of the task through Git history.

6. Naming Conventions

The system strictly follows a set of naming conventions, which aids in automated script recognition and management:

• Session ID Format: YYYYMMDD-<summary-slug> (limited to 60 characters). This ID serves as both the directory name and a human-readable session identifier.
• Worktree Path: ../<project-name>-wt-<task-slug>/. All task worktrees are created at the same level as the main project for easy access.
• Branch Naming: wt/YYYYMMDD/<task-slug>. Using the wt/ prefix as a namespace effectively avoids naming conflicts with regular development branches (like feature/, bugfix/).

State Management Explained

All data regarding the development session is persistently stored in the .worktree-flow/<session-id>/ directory of the base worktree. This design tightly integrates state data with the codebase while keeping them separate.

A typical directory structure looks like this:

.worktree-flow/
└── 20260204-fastlane-revenuecat-i18n/
    ├── session.json                    # Stores session metadata and the complete task list
    ├── lock.d/                         # Merge lock directory (core of atomic operations)
    │   └── owner                       # Identifies the current task holding the lock
    ├── integrate-fastlane/
    │   └── status.json                 # Independent status file for the "integrate-fastlane" task
    ├── integrate-revenuecat/
    │   └── status.json                 # Independent status file for the "integrate-revenuecat" task
    └── add-i18n/
        └── status.json                 # Independent status file for the "add-i18n" task

• session.json: The configuration center for the entire session, recording the results of task breakdown, conflict matrices, creation time, and other global information.
• lock.d/: A dynamic directory that only exists during merge operations, used to control concurrency.
• status.json: Each task directory has an independent status file, recording whether the task is in pending, in_progress, or completed status.

For detailed structure definitions of these JSON files, you can refer to the references/state-formats.md file in the project.

File Structure and Reference Documentation

To facilitate deep understanding and usage by developers, the Worktree Flow project itself is clearly structured and well-documented.

Key file structures include:

• SKILL.md: The core file containing the specific instruction sets for both Coordinator and Executor modes.
• README.md / README_CN.md: Project documentation.
• references/: A reference documentation directory containing deeper technical details.

  • state-formats.md: Detailed JSON Schema definitions.
  • coordinator-workflow.md: Detailed explanations on task decomposition strategies and conflict assessment matrices.
  • executor-workflow.md: Detailed flows for activation sequences, merge protocols, and error handling.
  • git-operations.md: A reference manual for all Git commands used in the skill.
• assets/templates/: Stores templates for all slash commands, such as wt-commit.md, wt-done.md, etc.

System Requirements

Before using Worktree Flow, please ensure your development environment meets the following basic requirements:

• Git: Version must be 2.5 or higher, as the git worktree feature was introduced in this version.
• Claude Code: The latest version is recommended to ensure full support for skill features.

Frequently Asked Questions

Q: What happens if two tasks modify the same file? How does Worktree Flow handle this?
A: The conflict assessment step in the Coordinator Mode will detect this file overlap and mark it as HIGH risk. The system will recommend a merge order (suggesting completing upstream dependent tasks first). While the system cannot automatically resolve logical conflicts, it minimizes issues through sequential control and risk warnings.

Q: How can I view the overall development progress of the current project?
A: You can use the /wt-status command in any worktree. It will display the status of the current task and also list the completion status of all other tasks in the session.

Q: Do I need to keep the worktree after a task is developed?
A: Once a task is successfully merged via /wt-done, the worktree and branch associated with that task have served their purpose. You can use the /wt-cleanup command to uniformly clean up these completed resources, keeping your working directory neat.

Q: What should I do if an error occurs during the merge process?
A: The Executor Workflow in Worktree Flow includes error handling mechanisms. If the merge fails, the system will preserve the scene and provide error messages. You may need to manually resolve conflicts (if any), then attempt the merge process again, or correct the code based on the error prompts.

Q: Does Worktree Flow support all types of projects?
A: Yes, as long as your project uses Git for version control and the Git version is higher than 2.5, Worktree Flow can be effective. It does not rely on specific programming languages or frameworks.

Conclusion

Worktree Flow provides a complete solution for parallel development with Claude Code by cleverly combining native Git Worktree capabilities with structured workflow protocols. It not only solves the technical challenges of multi-task concurrency but, more importantly, establishes a set of standardized collaboration protocols.

Through automated task decomposition, intelligent risk assessment, and strict merging protocols, developers can be liberated from tedious branch management and conflict resolution, focusing their energy on business logic implementation. Whether for individual developers handling complex features or teams developing large-scale projects, Worktree Flow is a powerful tool worth exploring and utilizing in depth.