Git Worktree Support

Run CodeBuddy in isolated workspaces for parallel development and safe isolation.

Overview

Git worktree allows you to have multiple working directories simultaneously within the same repository, each checked out to a different branch. CodeBuddy Code leverages this feature to provide:

• Parallel development: Perform experimental development without affecting the main workspace
• Safe isolation: All AI changes are made in a separate directory
• Zero storage overhead: Worktrees share Git objects without duplicating the entire repository
• Sub-agent isolation: Multiple AI sub-agents can work in parallel in independent worktrees
• tmux integration: Optionally run in a dedicated tmux session

Quick Start

# Create a worktree with an auto-generated name
codebuddy --worktree

# Create a worktree with a specific name
codebuddy --worktree feature-auth

# Run in a tmux session (recommended for long-running tasks)
codebuddy --worktree --tmux

# Create a worktree based on a PR/MR (for code review)
codebuddy --worktree "#123"                                    # GitHub PR number
codebuddy --worktree "https://github.com/owner/repo/pull/123" # GitHub PR URL
codebuddy --worktree "https://gitlab.com/owner/repo/-/merge_requests/456" # GitLab MR URL
codebuddy --worktree "https://cnb.woa.com/owner/repo/-/pulls/789" # CNB PR URL

Creating Within a Session

After starting a CodeBuddy Code session, you can create a worktree via natural language:

> start a worktree
> work in a worktree
> 启动 worktree

The AI will automatically invoke the EnterWorktree tool to create an isolated working directory and switch to it.

Note: This is only triggered when "worktree" is explicitly mentioned. Saying "create a branch for me" or "fix this bug" will not automatically create a worktree.

CLI Parameters

Parameter	Description	Example
--worktree [name]	Create and enter a worktree	--worktree or --worktree my-feature
--tmux	Run in a tmux session (requires tmux installed)	--worktree --tmux
--tmux-classic	Use classic tmux mode (without popup)	--worktree --tmux --tmux-classic

Workflow

Creating a Worktree

When starting with the --worktree parameter:

1. CodeBuddy creates a new worktree under the .codebuddy/worktrees/ directory
2. Automatically creates a corresponding branch (e.g., worktree-feature-auth), based on the remote default branch (usually main or master)
3. Switches the working directory to the worktree
4. Runs initialization (copies settings, creates symlinks, copies .worktreeinclude files, etc.)

Options on Exit

When you exit a worktree session, CodeBuddy detects changes and offers options:

• Keep Worktree: Preserve all changes and the branch for later continuation
• Remove Worktree: Clean up the worktree and associated branch
• Keep but exit tmux: (tmux mode) Preserve the worktree but close the tmux session

Change Detection

Before exiting, CodeBuddy checks for:

• Uncommitted file changes
• Unpushed commits

If no changes are detected, the worktree is automatically cleaned up.

Configuration

Configure worktree behavior in settings.json:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".next", ".cache", "dist"]
  }
}

Configuration Options

Option	Description	Default
symlinkDirectories	Directories to symlink from the main repository to the worktree	[]

Symlinked directories avoid redundant dependency installation in each worktree, saving time and disk space.

Syncing Local Ignored Files (.worktreeinclude)

Local configuration files like .env.local and .env.development are typically excluded by .gitignore, but new worktrees need them to function properly.

Solution: Create a .worktreeinclude file in the repository root listing files to copy (uses the same syntax as .gitignore):

# .worktreeinclude
# List local files to copy to new worktrees

# Environment variables
.env.local
.env.development.local
.env.test.local

# Local IDE configuration
.vscode/settings.json

# Local certificates or keys (if any)
certs/localhost.pem

These files are automatically copied from the main repository root each time a new worktree is created. Files are not re-copied when reusing an existing worktree.

Tip: .worktreeinclude should be committed to Git so all team members benefit.

Hooks Support

For non-Git version control systems or custom requirements, you can use hooks to control worktree creation and deletion:

WorktreeCreate Hook

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "/path/to/create-worktree.sh"
      }
    ]
  }
}

Input: JSON format containing the worktree name and session information Output: On success, outputs the absolute path of the worktree to stdout

WorktreeRemove Hook

{
  "hooks": {
    "WorktreeRemove": [
      {
        "command": "/path/to/remove-worktree.sh"
      }
    ]
  }
}

Input: JSON format containing the worktree path to be removed

tmux Integration

Use the --tmux parameter to run CodeBuddy in a dedicated tmux session:

# Basic usage
codebuddy --worktree --tmux

# Use classic mode (without popup)
codebuddy --worktree --tmux --tmux-classic

tmux Requirements

• tmux version 3.2 or higher (for popup support)
• Automatically falls back to classic mode if the version is lower

Exiting a tmux Session

• Press Ctrl+D or type /exit to quit CodeBuddy
• The tmux session will be preserved or closed based on your choice

Directory Structure

your-repo/
├── .codebuddy/
│   └── worktrees/
│       ├── feature-auth/      # worktree directory
│       │   ├── node_modules -> ../../node_modules  # symlink
│       │   └── ...
│       └── fix-bug-123/
├── .worktreeinclude           # defines local files to copy (recommended to commit)
└── ...

Manual Worktree Management

CodeBuddy Code automatically handles worktree cleanup when a session exits. However, sometimes you need to manage worktrees outside of a session — for example, cleaning up leftover worktrees or having more flexible control over branches and directory locations.

Cleaning Up Worktrees Outside a Session

Use Git commands directly:

# List all current worktrees
git worktree list

# Remove a specific worktree (when there are no uncommitted changes)
git worktree remove .codebuddy/worktrees/feature-auth

# Force remove (when there are uncommitted changes)
git worktree remove --force .codebuddy/worktrees/feature-auth

# Also delete the corresponding branch
git branch -D worktree-feature-auth

# Prune stale worktree references (directory deleted but Git still tracks it)
git worktree prune

Creating Worktrees Directly with Git

Sometimes you need to check out an existing branch, or place the worktree outside the repository directory. You can bypass CodeBuddy Code and create worktrees directly with Git, then start a session inside:

# Create a new branch and worktree (outside the repository)
git worktree add ../project-feature-a -b feature-a

# Check out an existing branch
git worktree add ../project-bugfix bugfix-123

# Enter the worktree and start CodeBuddy Code
cd ../project-feature-a && codebuddy

# Clean up when done
git worktree remove ../project-feature-a

This approach is suitable for scenarios where you need to place the worktree in a specific location or reuse an existing branch.

Sub-agent Isolation

When having CodeBuddy Code launch multiple sub-agents to work in parallel, each sub-agent can run in an independent worktree to avoid file conflicts.

What is isolation: worktree

Adding isolation: worktree to a custom Agent's frontmatter means that each time the Task tool launches this Agent, the system automatically creates an independent worktree for it instead of running directly in the main repository directory.

This means:

• Multiple sub-agents can modify files with the same name simultaneously without affecting each other
• The main repository directory stays clean — sub-agents' temporary changes do not pollute it
• After a sub-agent finishes, the worktree is kept or removed as needed

Creating an Isolated Custom Agent

Create a Markdown file in the .codebuddy/agents/ directory:

---
name: isolated-worker
description: Works in an independent worktree without affecting the main repository
isolation: worktree
---

You are running in an isolated git worktree.
Focus on completing the task assigned to you, and report results when done.

How It Works

When the main Agent launches this Agent using the Task tool, an independent worktree is automatically created for it. Multiple sub-agents can work simultaneously, even modifying the same files without conflicts.

After a sub-agent finishes:

• No changes: The worktree is automatically deleted
• Has changes: The worktree is preserved, and the main Agent receives the worktree location information

Verifying Isolation

> Use the isolated-worker agent to create test.txt in the current directory with the content "hello"

Check the result:

# The file does not exist in the main repository
ls test.txt
# → No such file or directory ✓

# The file is in the sub-agent's worktree
ls .codebuddy/worktrees/agent-xxx/test.txt
# → exists ✓

Typical Use Cases

Scenario 1: Handling Urgent Bugs in Parallel

Problem: You're in the middle of developing a new feature with half-written code, and an urgent bug needs fixing.

Solution:

# Terminal 1: Continue developing the new feature
codebuddy --worktree feature-payment

# Terminal 2: Fix the bug separately, without interference
codebuddy --worktree hotfix-login-crash

Both worktrees are open simultaneously without affecting each other. Once the bug is fixed and a PR is submitted, switch back to feature development.

Scenario 2: High-Risk Refactoring

Problem: You want to attempt a large-scale refactor but aren't sure if it will succeed, and you don't want to pollute the main repository.

Solution:

codebuddy --worktree refactor-esm

In the session:

> Help me migrate the src/core directory from CommonJS to ESM

Result:

• Success: Commit, push PR, merge
• Failure: Choose "Remove worktree" on exit — all changes are discarded with one click

Scenario 3: Reviewing a PR

Problem: You want to run a colleague's PR code locally without polluting your working directory.

Solution:

codebuddy --worktree "#456"

In the session:

> Help me review what this PR changed and check for potential issues
> Run the tests

Exit when done — the worktree is automatically cleaned up.

Scenario 4: Parallel Tasks

Problem: You have multiple independent tasks (writing docs, adding tests, developing a new API) and want to work on them separately.

Solution:

codebuddy --worktree task-docs --tmux
codebuddy --worktree task-tests --tmux
codebuddy --worktree task-new-api --tmux

Each worktree lets the AI focus on one thing, with tmux enabling true parallel work.

Scenario 5: Sub-agent Collaboration

Problem: A large task requires multiple AI agents to process different modules in parallel.

Solution:

First create an isolated Agent (see the "Sub-agent Isolation" section above), then:

> Use three parallel api-worker sub-agents:
  The first handles the src/api/user/ directory
  The second handles the src/api/order/ directory
  The third handles the src/api/product/ directory

Three sub-agents each work in independent worktrees — even if they modify shared files, there are no conflicts.

FAQ

Q: Will worktrees take up a lot of disk space?

No. All worktrees share the Git object database and only need to store the working files themselves. With symlinkDirectories configured, large directories are also shared, resulting in virtually no extra space usage.

Q: When reusing an existing worktree, will files like .env.local be re-copied?

No. When reusing, the existing directory is entered directly, skipping initialization. To sync new configurations, remove the worktree and recreate it:

git worktree remove --force .codebuddy/worktrees/my-feature
git branch -D worktree-my-feature
codebuddy --worktree my-feature

Q: Will commits in a worktree affect the main repository?

No. A worktree has its own branch, and commits are only made on that branch. To merge into the main branch, follow the normal PR process or manually run git merge.

Q: What if the worktree creation was interrupted, leaving an incomplete directory?

git worktree remove --force .codebuddy/worktrees/<name>
git branch -D worktree-<name>

Then recreate it.

Q: symlinkDirectories is configured but not working?

Reusing an existing worktree does not re-run initialization. Remove the old worktree and recreate it.

Q: Is sub-agent isolation a security sandbox?

No. Sub-agents are isolated at the file level, but they have the same permissions as the main Agent and can theoretically access files outside the worktree. This feature is designed to prevent file conflicts between multiple Agents, not to enforce security restrictions.

Important Notes

• Git repository required: The --worktree parameter only works within a Git repository
• Branch naming: Automatically created branches are prefixed with worktree-
• Cleanup: Long-unused worktrees are not automatically cleaned up — they need to be manually deleted or cleaned using the /rewind command
• Symlinks: Some tools may not support symlinked directories — configure based on your project's needs

Related Documentation

• CLI Reference - Complete command-line parameter reference
• Hooks Reference - Detailed Hook system documentation
• Settings Configuration - Configuration file reference