Git Worktrees

Overview Traditional branching models often struggle with the speed of AI-driven development. If you try to run multiple Claude Code agents on a single directory, they inevitably collide, overwriting files and corrupting the state of your local environment. Git Worktrees solve this by allowing you to have multiple branches checked out simultaneously in separate folders. This setup enables true parallel processing for coding agents. Prerequisites To follow this guide, you should be comfortable with Git fundamentals like merging and commits. You will also need Claude Code version 2.15.0 or higher installed on your machine, along with a project to test—like a Laravel application. Key Libraries & Tools * **Git**: The core version control system providing the worktree functionality. * **Claude Code**: The CLI agent that now supports native worktree isolation flags. * **VS Code**: An IDE used here to visualize the worktree directory structure and resolve merge conflicts. Code Walkthrough To launch an isolated agent, use the `--worktree` flag followed by a descriptive name. This creates a dedicated folder under `.claude/worktrees/` containing a full replica of your project. ```bash Launch an agent for the 'About' page claude --worktree about-page --dangerously-skip-permissions Launch a second agent for the 'Contact' page in a new terminal claude --worktree contact-page --dangerously-skip-permissions ``` Once the agents finish their tasks, you must commit the changes within those specific worktrees. After committing, return to your main branch to merge the results. Git treats these as separate paths, so use the worktree prefix during the merge process: ```bash git merge claude-worktrees/about-page ``` Syntax Notes The `--worktree` flag is the primary addition to the Claude Code syntax. It instructs the agent to operate within a specific subdirectory rather than the root, preventing the "unpredictable consequences" of two agents modifying the same `routes/web.php` file at once. Practical Examples Imagine requesting three different UI designs for a single dashboard. Instead of waiting for one to finish, you can spawn three agents in separate worktrees. You can then compare the rendered results across three different folders before deciding which one to merge into your main branch. Tips & Gotchas Watch out for environment files. Worktrees often miss local `.env` files or `vendor` folders if they aren't properly symlinked. You might see errors regarding missing encryption keys or failed formatting tools. While the AI usually ignores these and continues, always verify the generated code's integrity before final integration.