Skip to content
SCC CLI

Git Worktrees

Git worktrees let you check out multiple branches simultaneously in different directories. SCC uses worktrees to isolate AI experiments and enable parallel development.

Worktree Location (CRITICAL)

Section titled “Worktree Location (CRITICAL)”

When you create a worktree, SCC places it in a sibling directory:

Git Worktree Structure
Git Worktree Structure

Pattern: <repo-parent>/<repo-name>-worktrees/<feature-name>/

Example:

  • Main repo: /Users/dev/myproject/
  • Worktrees: /Users/dev/myproject-worktrees/feature-auth/
  • NOT: /Users/dev/myproject/.worktrees/feature-auth/ ❌

This external placement ensures:

  • Main repository stays clean (no .worktrees/ directory)
  • No confusion with project files
  • Easy to .gitignore if needed (though it’s already outside)

Why Use Worktrees?

Section titled “Why Use Worktrees?”
Terminal window
# Working on feature, need to fix urgent bug
git stash
git checkout main
git checkout -b bugfix-urgent
# Fix bug...
git checkout feature-branch
git stash pop
# Hope you didn't lose anything!

Creating Worktrees

Section titled “Creating Worktrees”

Basic Creation

Section titled “Basic Creation”
Terminal window
scc worktree create ~/project feature-auth

This creates:

  • Directory: ~/project-worktrees/feature-auth/ (outside the repository)
  • Branch: scc/feature-auth

From Existing Branch

Section titled “From Existing Branch”
Terminal window
scc worktree create ~/project feature-auth --branch existing-branch

With Immediate Launch

Section titled “With Immediate Launch”
Terminal window
scc worktree create ~/project feature-auth --launch

Creates the worktree and immediately starts SCC in it.

Entering Worktrees

Section titled “Entering Worktrees”

Primary Method (Subshell)

Section titled “Primary Method (Subshell)”
Terminal window
scc worktree enter feature-auth

This opens a subshell in the worktree directory. Type exit to return.

Power User Method (Shell Wrapper)

Section titled “Power User Method (Shell Wrapper)”

Add this to your ~/.bashrc or ~/.zshrc:

Terminal window
wt() {
  local p
  p="$(scc worktree switch "$@")" || return $?
  cd "$p" || return 1
}

Then use:

Terminal window
wt feature-auth    # cd to worktree
wt ^               # cd to main branch
wt -               # cd to previous worktree

Listing Worktrees

Section titled “Listing Worktrees”

Basic List

Section titled “Basic List”
Terminal window
scc worktree list

With Git Status

Section titled “With Git Status”
Terminal window
scc worktree list -v

Output:

~/project-worktrees/feature-auth [scc/feature-auth]
  +2 !1 ?3


~/project-worktrees/bugfix-login [scc/bugfix-login]
  .

Status Indicators

Section titled “Status Indicators”
SymbolMeaning
+NN staged files
!NN modified files
?NN untracked files
.Clean worktree
…Status timed out

Switching Worktrees

Section titled “Switching Worktrees”

Interactive Picker

Section titled “Interactive Picker”
Terminal window
scc worktree select

Direct Switch

Section titled “Direct Switch”
Terminal window
scc worktree switch feature-auth

Quick Navigation

Section titled “Quick Navigation”
Terminal window
scc worktree enter ^    # Main branch
scc worktree enter -    # Previous worktree

Fuzzy Matching

Section titled “Fuzzy Matching”
Terminal window
scc worktree switch auth    # Matches feature-auth
scc worktree switch scc/feature-x  # Match by full branch name

Removing Worktrees

Section titled “Removing Worktrees”

Remove Specific Worktree

Section titled “Remove Specific Worktree”
Terminal window
scc worktree remove feature-auth

Prune All Stale Worktrees

Section titled “Prune All Stale Worktrees”
Terminal window
# Preview what would be removed
scc worktree prune -n


# Actually prune
scc worktree prune

Worktree + SCC Workflow

Section titled “Worktree + SCC Workflow”

Typical Feature Development

Section titled “Typical Feature Development”

  1. Create worktree for the feature

    Terminal window
    scc worktree create ~/project feature-payments

  2. Enter the worktree

    Terminal window
    scc worktree enter feature-payments

  3. Start SCC session

    Terminal window
    scc

  4. Work with Claude Code

    Claude makes changes in the isolated branch. Main stays clean.

  5. When done, exit and clean up

    Terminal window
    exit  # Leave worktree subshell
    

    # If feature is complete and merged:
    scc worktree remove feature-payments

Multiple Features in Parallel

Section titled “Multiple Features in Parallel”
Terminal window
# Terminal 1: Working on payments
scc worktree enter feature-payments
scc


# Terminal 2: Working on auth
scc worktree enter feature-auth
scc


# Terminal 3: Quick bugfix
scc worktree enter bugfix-urgent
scc

Each terminal has its own Claude session in its own isolated branch.

Branch Naming

Section titled “Branch Naming”

SCC prefixes worktree branches with scc/:

Worktree NameBranch Created
feature-authscc/feature-auth
bugfix-loginscc/bugfix-login

Advanced: Worktree Architecture

Section titled “Advanced: Worktree Architecture”

Worktrees share the same .git repository as your main branch but have separate working directories. This allows:

  • Multiple branches checked out simultaneously
  • Shared Git history and configuration
  • Independent file states per worktree
  • No branch switching in your main repository

Troubleshooting

Section titled “Troubleshooting”

”Worktree already exists”

Section titled “”Worktree already exists””

A worktree with that name exists. Either:

  • Use a different name
  • Remove the existing worktree: scc worktree remove feature-auth

”Cannot create worktree: no commits”

Section titled “”Cannot create worktree: no commits””

The repository needs at least one commit:

Terminal window
git commit --allow-empty -m "Initial commit"

Worktree shows in list but directory missing

Section titled “Worktree shows in list but directory missing”

The worktree was deleted externally. Prune it:

Terminal window
scc worktree prune