Git worktrees are the technology that enables Spec Kitty’s parallel development model. This document explains what worktrees are, why Spec Kitty uses them, and how they work.
A git worktree is a linked working directory that lets you check out multiple branches simultaneously, each in its own directory. Unlike cloning a repository multiple times, all worktrees share the same .git directory and repository history.
Normal git workflow (one branch at a time):
# You can only have one branch checked out
git checkout feature-a
# To work on feature-b, you must switch branches
git checkout feature-b # Now you're on feature-b, feature-a is gone
With worktrees (multiple branches simultaneously):
# Main repo stays on main branch
my-repo/ # main branch
# Each worktree has its own branch
.worktrees/feature-a/ # feature-a branch
.worktrees/feature-b/ # feature-b branch
You can now have three terminal windows open, each in a different directory, each on a different branch, all editing the same repository.
Without worktrees, only one developer (or agent) can work at a time because git only allows one branch checked out per repository. With worktrees:
.worktrees/feature-WP01/ on WP01.worktrees/feature-WP02/ on WP02.worktrees/feature-WP03/ on WP03All three agents work simultaneously, each with their own files, their own uncommitted changes, and their own branch.
Problems with shared workspaces:
config.py, breaks itWith workspace-per-WP:
config.py only exists in WP01’s workspaceSpec Kitty’s parallel model requires:
Git worktrees provide all three.
When you clone a repository, git creates a .git directory containing:
A worktree doesn’t duplicate this. Instead, it creates a small file that points back to the main .git directory.
my-repo/
├── .git/ # The real git database
├── src/ # Your source files
├── .worktrees/
│ ├── feature-WP01/
│ │ ├── .git # Just a pointer file
│ │ └── src/ # Separate copy of source files
│ └── feature-WP02/
│ ├── .git # Just a pointer file
│ └── src/ # Another separate copy
All worktrees share:
.git)Each worktree has its own:
This means Agent A can have uncommitted changes to config.py without affecting Agent B’s config.py.
| Aspect | Worktree | Clone |
|---|---|---|
| Repository data | Shared | Duplicated |
| Disk space | Minimal | Full copy |
| Branches | Shared | Independent |
| Fetching/pushing | Once for all | Once per clone |
| Merging between | Direct (same repo) | Requires remote |
| Independence | Partial | Complete |
Use worktrees when:
Use clones when:
git worktree list
Example output:
/path/to/my-repo abc1234 [main]
/path/to/my-repo/.worktrees/feature-WP01 def5678 [feature-WP01]
/path/to/my-repo/.worktrees/feature-WP02 ghi9012 [feature-WP02]
# Create worktree with existing branch
git worktree add .worktrees/feature-WP01 feature-WP01
# Create worktree and create new branch
git worktree add -b feature-WP01 .worktrees/feature-WP01
# Create worktree from specific commit/branch
git worktree add -b feature-WP02 .worktrees/feature-WP02 feature-WP01
# Clean removal (worktree must be clean)
git worktree remove .worktrees/feature-WP01
# Force removal (discards uncommitted changes)
git worktree remove --force .worktrees/feature-WP01
# Prune worktrees whose directories no longer exist
git worktree prune
A sparse checkout limits which files appear in your working directory. Combined with worktrees, this allows each WP workspace to have only the files it needs.
Without sparse checkout:
.worktrees/feature-WP01/
├── docs/ # Agent doesn't need docs
├── tests/ # Agent doesn't need tests
├── src/
│ └── module.py # Agent only needs this
└── README.md # Agent doesn't need this
With sparse checkout:
.worktrees/feature-WP01/
└── src/
└── module.py # Only what the agent needs
Spec Kitty uses sparse checkouts to:
kitty-specs/ directory only in the main repo# Enable sparse checkout
git sparse-checkout init --cone
# Include only specific paths
git sparse-checkout set src/ tests/
Error:
fatal: 'feature-WP01' already has a worktree at '.worktrees/feature-WP01'
Cause: You’re trying to create a worktree for a branch that’s already checked out somewhere.
Solution:
# Find where it's checked out
git worktree list
# Either remove the existing worktree
git worktree remove .worktrees/feature-WP01
# Or use that existing worktree instead
cd .worktrees/feature-WP01
Error:
fatal: 'feature-WP01' is already checked out at '/path/to/other/worktree'
Cause: Git won’t let two worktrees have the same branch checked out.
Solution:
# Find the other worktree
git worktree list
# Remove it if not needed
git worktree remove /path/to/other/worktree
# Or work in the existing worktree
cd /path/to/other/worktree
If Spec Kitty or your system crashes mid-operation, worktrees may be left in an inconsistent state.
Symptoms:
git worktree list shows non-existent directoriesSolution:
# Clean up stale worktree references
git worktree prune
# Force unlock if needed
git worktree unlock .worktrees/stuck-worktree
# Verify cleanup
git worktree list
Symptom: Commits in worktree aren’t on any branch.
Cause: Worktree was created from a commit, not a branch.
Solution:
cd .worktrees/feature-WP01
git checkout -b feature-WP01 # Create and switch to branch
Spec Kitty also supports jujutsu (jj) as an alternative to git. Here’s how they compare:
| Aspect | Git Worktrees | jj Workspaces |
|---|---|---|
| Isolation | Separate working trees, same repo | Same repo, different commits |
| Rebase | Manual (git rebase) |
Automatic on sync |
| Conflicts | Blocking (must resolve immediately) | Non-blocking (stored in files) |
| Multi-parent | Manual merge required | Automatic |
| Undo | Limited (reflog) | Full operation history |
When to use git worktrees:
When to use jj workspaces:
See Jujutsu for Multi-Agent Development for details on why jj is recommended.
This document explains git worktrees for understanding. For practical steps in Spec Kitty, see the how-to guides.