Kiwi Code DocsWorktree Mode
Work in isolated git worktrees so the AI can experiment without touching your main branch.
Worktree Mode
Worktree mode lets the AI work in an isolated copy of your repository. Your main branch stays clean — review the AI's changes and merge when you're ready.
Why use worktrees?
- Keep your working branch clean while the AI experiments
- Review AI changes before merging
- Run multiple AI sessions on different branches in parallel
- Safely test ideas without fear of breaking things
Quick Start
# Auto-generate a worktree name
kiwi -w
# Use a specific name
kiwi -w add-jwt-auth
# Also works with kiwi-runtime
kiwi-runtime -w refactor-dbKiwi creates the worktree, switches into it, and launches — all in one command.
Workflow
Start a worktree session
kiwi -w add-rate-limitingThis creates a new branch and worktree at .kiwi/worktrees/add-rate-limiting/.
Work with the AI
In the TUI, ask the AI to make changes. Everything happens inside the worktree — your main branch is untouched.
Add rate limiting middleware to the Express APIReview the changes
cd .kiwi/worktrees/add-rate-limiting
git diff mainMerge when ready
git checkout main
git merge add-rate-limitingClean up (optional)
git worktree remove .kiwi/worktrees/add-rate-limitingNaming
| Input | What happens |
|---|---|
kiwi -w | Auto-generates a name like calm-thinking-owl |
kiwi -w my-feature | Uses my-feature as branch and worktree name |
kiwi -w feature/auth | Slash-separated names work too |
Resuming Work
If a worktree already exists, Kiwi reuses it:
# First session — creates the worktree
kiwi -w build-api
# Later — resumes the same worktree
kiwi -w build-apiRequirements
- Git must be installed
- Must run from inside a git repository
- The repo must have at least one commit
Troubleshooting
"Branch is already checked out in another worktree"
Use a different name, or remove the conflicting worktree:
git worktree list
git worktree remove <path>Stale worktree errors
If a worktree directory was deleted manually:
git worktree pruneKiwi usually auto-heals this, but running prune manually always works.