Git Worktrees for Parallel Claude Code Sessions
On its anodised aluminium body, KM16 Macropad carries sixteen keycaps plus one large knob and two small ones. Its VIA-remappable outputs can select task terminals, but Git worktrees provide the file isolation those terminals actually need.
Why do parallel agents need worktrees?
Two agents in one working directory can overwrite files, change the checked-out branch and confuse each other's uncommitted state. Git worktrees attach additional working directories to the same repository so different branches can be checked out at the same time.
Claude's documentation recommends separate worktrees for parallel sessions because each session is then tied to its own directory. Isolation is incomplete outside Git: local services, databases, generated caches and network ports may still be shared, so assign those resources separately when necessary.
How do you create and organise the worktrees?
From the main repository, use Git's worktree add command with an explicit sibling path and new task branch. A directory scheme such as project-worktrees followed by a short task name makes the boundary obvious. Run Git status inside the new directory before starting Claude.
Keep a ledger containing the task, path, branch, base revision and validation command. Claude Code also has current CLI worktree support, but inspect the installed help before using it and understand the branch and directory it creates.
How do you pair each worktree with a tmux window?
Create a named tmux window whose starting directory is the worktree, then launch one Claude session there. Align the task portion of the worktree, branch, tmux title and Claude session name. The repetition makes a mismatch easier to spot during review.
A macropad key may select that tmux window through a direct root binding. It should reveal the window only. Read the directory and branch before responding, and keep approval plus Enter on the normal keyboard.
What cleanup does the pattern need?
Commit, stash or deliberately discard work only after review. Compare the task branch with its base and run its verification command from the worktree. Merge through the project's normal process, then use Git's worktree remove command rather than deleting the directory by hand.
Git normally refuses to remove a dirty worktree without force. That resistance protects uncommitted files. Use worktree list to audit what remains, prune stale administrative entries when appropriate and repair links if directories were moved.
The KM16 Macropad can make four active tasks quick to reach, but it does not make four branches safe to merge. Remove or relabel each navigation key when its worktree closes, and preserve the task ledger outside temporary directories.