Git Worktrees

ChatCLI’s /worktree command integrates with the git worktrees system to allow isolated work on multiple branches simultaneously. Instead of git stash and git checkout, you create separate worktrees and switch between them with a single command.

Git worktrees allow you to have multiple working copies of the same repository, each on a different branch, sharing the same .git. ChatCLI automates the creation, listing, and removal of these worktrees.

Concept

A worktree is a separate directory linked to the same Git repository but on a different branch. This allows:

my-project/                 (main)
my-project-feature-auth/    (feature/auth)  <- worktree
my-project-fix-bug-123/     (fix/bug-123)   <- worktree

They all share the same .git, commits, and history. You can work on each branch without interfering with the others.

Commands

Command	Description
`/worktree create <branch>`	Creates a new worktree for the specified branch
`/worktree list`	Lists all active worktrees for the repository
`/worktree remove <branch>`	Removes an existing worktree
`/worktree status`	Shows the current worktree status (branch, modified files)

Creating a Worktree

/worktree create feature/auth

Worktree created:
  Branch: feature/auth
  Path:   /Users/dev/my-project-feature-auth/
  CWD changed to: /Users/dev/my-project-feature-auth/

Tip: Use /worktree list to see all active worktrees.

Automatic branch detection

If the branch already exists in the repository (local or remote), ChatCLI uses it directly. If it doesn’t exist, it creates a new branch from the current HEAD.

Directory creation

The worktree directory is created alongside the repository root, with a name based on the branch (slashes replaced with hyphens).

CWD change

ChatCLI automatically changes the working directory to the new worktree, allowing subsequent commands to operate in the correct context.

The branch can be an existing branch (local or remote) or a new branch. ChatCLI automatically detects which and acts accordingly.

Listing Worktrees

/worktree list

Active worktrees:
  * /Users/dev/my-project/                  main          (current)
    /Users/dev/my-project-feature-auth/     feature/auth  3 modified files
    /Users/dev/my-project-fix-bug-123/      fix/bug-123   clean

Removing a Worktree

/worktree remove feature/auth

Worktree removed:
  Branch: feature/auth
  Path:   /Users/dev/my-project-feature-auth/ (deleted)

Note: The branch 'feature/auth' was NOT deleted. Use git branch -d to remove it.

Removing a worktree deletes the directory but does not delete the branch. Uncommitted changes will be lost. Always commit or stash before removing.

Worktree Status

/worktree status

Current worktree:
  Path:   /Users/dev/my-project-feature-auth/
  Branch: feature/auth
  Ahead:  2 commits (vs origin/feature/auth)
  Files:  3 modified, 1 untracked

  Modified:
    M  auth/handler.go
    M  auth/middleware.go
    M  auth/jwt.go
    ?  auth/refresh_token.go

Typical Workflows

Parallel feature
Urgent hotfix
PR review

Work on a feature without affecting the main branch:

# Create worktree for the feature
/worktree create feature/auth

# Work normally (CWD already changed)
/coder Implement the JWT authentication module

# Go back to the main worktree
/worktree create main
# (detects that main already exists and just changes CWD)

Fix a bug without losing work in progress:

# You're working on feature/auth...
# Urgent bug in production!

/worktree create hotfix/fix-login

# Fix the bug
/coder Fix the login bug causing infinite redirect

# Go back to the feature
/worktree create feature/auth

Review a PR without leaving your branch:

# Create worktree for the PR branch
/worktree create feature/new-api

# Analyze the code
/plan
/agent Analyze the changes in this branch and identify potential issues
# or, on a single line:
# /plan Analyze the changes in this branch and identify potential issues

# Remove when done
/worktree remove feature/new-api

Technical Details

Directory Location

Worktrees are created alongside the repository root:

/Users/dev/
  my-project/                     <- original repository
  my-project-feature-auth/        <- worktree (branch: feature/auth)
  my-project-fix-bug-123/         <- worktree (branch: fix/bug-123)

The directory name is composed as <repo-name>-<branch>, where slashes (/) in the branch are replaced with hyphens (-).

Automatic CWD Change

When creating or selecting a worktree, ChatCLI automatically changes the CWD. This ensures that:

Agent/coder commands operate on the correct files
File search (search, tree) reflects the correct branch
Bootstrap files (SOUL.md, RULES.md) are detected correctly

Compatibility

Requirement	Details
Git	>= 2.15.0 (worktree support)
Repository	Must be a Git repository (non-bare)
Permissions	Write access to the parent directory of the repository

Home

Getting Started

Core Concepts

Features

Security

Support

Concept

Commands

Creating a Worktree

Listing Worktrees

Removing a Worktree

Worktree Status

Typical Workflows

Technical Details

Directory Location

Automatic CWD Change

Compatibility

Next Steps

Sessions

Coder Mode

​Concept

​Commands

​Creating a Worktree

​Listing Worktrees

​Removing a Worktree

​Worktree Status

​Typical Workflows

​Technical Details

​Directory Location

​Automatic CWD Change

​Compatibility

​Next Steps

Sessions

Coder Mode

Concept

Commands

Creating a Worktree

Listing Worktrees

Removing a Worktree

Worktree Status

Typical Workflows

Technical Details

Directory Location

Automatic CWD Change

Compatibility

Next Steps