Claude Code Worktrees and Gitflow: The SWARECO Engineering Playbook
Orr Yakobi
Claude Code has built-in worktree support. On a Gitflow repository, you probably cannot use it.
The --worktree flag branches from your repository's default branch, and its baseRef setting accepts only fresh or head. You cannot set it to a specific branch name. If your feature branches come off the develop branch, you must create the worktree with Git yourself.
This single constraint shapes our entire workflow. This is the parallel-delivery section of SWARECO's internal engineering standard. We will explain how we run three Claude Code sessions at once on a Gitflow repository, what each worktree must not share, and what goes wrong when you skip a step.
What a Git worktree is, and why it matters here
A Git worktree is a second working directory that is attached to the same repository. Worktrees share history, objects, and remotes.
Each one has its own checked-out files, its own branch, its own HEAD, and its own index. You do not clone anything twice, so you avoid paying the disk space for a second copy of the repository's history.
For Claude Code, this isolation is the entire point. Two sessions editing one folder will collide because they both write files and neither is aware of the other. Separate worktrees make concurrent, parallel sessions safe by construction, not by discipline.
The reason to want concurrency shows up in Anthropic's own research. Across about 400,000 interactive sessions from roughly 235,000 people between October 2025 and April 2026, people made about 70% of the planning decisions but only 20% of the execution decisions. The engineer's time has moved to the beginning and end of the work. Watching one session execute is the waste that parallelism removes.
The same research found that expert sessions set off action chains more than twice as long, with 12 actions against about five for novices. The real advantage comes from a precise instruction and a fast correction, not from typing.
Claude Code's built-in worktrees, and where they stop
If you pass --worktree (or -w) with a name, Claude Code creates an isolated worktree and starts a session in it. By default, it creates the worktree under .claude/worktrees/<name>/.
It also creates a new branch named worktree-<name>, which is branched from the repository's default branch.
This behavior is perfect for a trunk-based repository but completely wrong for Gitflow. In a Gitflow model, feature branches originate from develop, not main. The worktree.baseRef setting cannot name a branch. It only accepts fresh (the default branch) or head (your current location). There is no third option.
So, our standard practice is to create the worktree with Git directly, which is what the official documentation recommends. You lose the convenience of a single flag, but you maintain your branching model. We find this to be the better trade.
Starting a ticket
From your primary checkout, run these commands.
git fetch origin
git worktree add ../myapp-ABC-123 \
-b feature/ABC-123 origin/develop
code ../myapp-ABC-123Next, open that new folder in its own editor window. Start Claude there in plan mode with a prompt that asks for a plan before generating any code.
In VS Code, the extension commands are Claude Code: Open in New Tab and Open in New Window. For concurrent edits, each window must point to a different worktree folder, not a different tab in the same window.
We are considering a bin/ticket start ABC-123 wrapper script so our engineers do not have to remember the specific plumbing. This is a proposal and not something we currently run.
The unit of parallel work
One ticket = one feature branch = one worktree = one primary session.
This rule is our entire operating model in one line. It is what allows the workflow to survive across three simultaneous streams of work. It keeps ownership clear, stops two sessions from editing the same branch, and makes every pull request traceable to a single ticket and its acceptance checklist.
We start with three concurrent streams per engineer: a primary feature, a second small independent change, and a third for investigation or review. Two to four streams is a control range, not a quota. We reduce it when changes overlap heavily, when migrations conflict, or when the review queue grows. The queue is the real constraint, not the agent.
What each worktree must not share
This is where parallel Claude Code sessions typically break, and it is worth being specific about the details.
- Safe to share: Git objects, history, and remotes; package manager caches; read-only development service endpoints.
- Isolate per worktree:
.envfiles and any ignored configuration, development and test databases, server ports and process IDs, local storage,tmpdirectories and job queues, and anything sensitive to migrations.
The Rails rule: give every worktree distinct development and test database names before you allow a migration to run. When two worktrees share one database, one stream can silently change the schema assumptions of another. The failure then surfaces somewhere unrelated an hour later.
There is a supported way to automate this that we found while fact-checking this page. Claude Code has WorktreeCreate and WorktreeRemove hook events. These hooks fire regardless of whether the worktree came from the --worktree flag or from git worktree add.
Setting up per-worktree databases and ports belongs in these hooks, not in a wrapper script or a wiki page nobody reads. The argument for putting rules where the tool will actually read them is the same one behind a CLAUDE.md that earns its length.
Merging, then cleaning up
From the ticket's worktree, push the branch and open a pull request against develop.
git push -u origin feature/ABC-123Continuous integration, agent review, and human approval all run before the merge. We keep the develop branch protected and require passing checks.
Agents do not merge code. The merge is the final architecture and risk decision, and it stays with a person.
After the merge is complete, from your primary checkout, you clean up.
git worktree remove ../myapp-ABC-123
git branch -d feature/ABC-123You must remove the worktree before deleting the branch. Never force the removal while work is uncommitted. Worktrees that are left around are how a stale branch gets edited by mistake three weeks later.
When a worktree is the wrong tool
A Claude Code worktree is for independent tickets that edit code. Three other work shapes exist, and they are not interchangeable.
| Approach | What it gives you | Best for | Status |
|---|---|---|---|
| Several conversations in one window | Separate histories and context | Planning, research, read-only review | Use now |
| Worktree sessions | Separate files and branches | Independent tickets that change code | The standard |
| Agent view | One screen for dispatching and watching sessions | Independent background tasks | Research preview |
| Agent teams | A lead session coordinating teammates | Work that genuinely needs coordination | Experimental, off by default |
Agent teams are enabled with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable. Teammates need clear file ownership, or they will collide just like two sessions in one folder do.
Our adoption sequence is deliberate. We start with manual worktrees first and a wrapper script second. An agent view pilot comes third, and we only use agent teams for a use case that has proven it needs them.
What goes wrong
These are the most common failures we have observed.
| Failure | What it costs you |
|---|---|
| Several editing sessions in one folder | File changes collide and the context becomes unreliable |
| Ten agents on day one | Review queues and merge conflicts erase the speed gain |
| Vague tickets | The agent invents requirements, and you pay for the rework |
| A shared database during migrations | One stream changes the schema another is assuming |
| An agent reviewing only its own work | The same blind spots survive into the pull request |
| Autonomous merge | You give away the final architecture and risk decision |
Every one of these is a failure of discipline, not a failure of tooling. That is the point. Parallelism increases output. Discipline decides whether that output becomes production value.
How to adopt it without guessing
You should run this process on one team or one repository for two weeks before changing a company-wide standard. Capture a baseline first. This includes cycle time, deployment frequency, change fail rate, and rework after review.
Then, hold roughly three streams per engineer and watch the review queue daily.
Do not set aggressive targets before you have the baseline. The test is simple: faster delivery, with stable or better quality, and a review queue the team can clear every day. If the queue grows, the answer is fewer streams, not more hours.
The files that go with this guide are published at github.com/SWARECO/dotclaude under an MIT licence. This includes a rules file, a ticket-writing skill, a recurring audit command, and a pull request reviewer. Take what is useful.
SWARECO runs dedicated engineering teams for founders and CTOs, and this is the standard those teams work to. The AI project manager we built and our scheduled Claude Code runs both sit on this same foundation.
Other Articles
We build the engineering. You build the business.
If you are trying to figure out whether SWARECO is the right fit for what you are building, the best way to find out is to talk. Tell us what you have. We will be direct about what we can do and how we would approach it.