Skip to main content
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

CommandDescription
/worktree create <branch>Creates a new worktree for the specified branch
/worktree listLists all active worktrees for the repository
/worktree remove <branch>Removes an existing worktree
/worktree statusShows 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.
1

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.
2

Directory creation

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

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

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)

​
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

RequirementDetails
Git>= 2.15.0 (worktree support)
RepositoryMust be a Git repository (non-bare)
PermissionsWrite access to the parent directory of the repository

​
Next Steps

Sessions

Combine worktrees with sessions for persistent context per branch.

Coder Mode

Use coder mode with worktrees for isolated engineering per branch.