Parallel sessions and git worktrees: run several Claude Code agents without collisions

What shipped this week

Let's start with yesterday's CLI release. Claude Code 2.1.161 landed on June second, and the headline for daily drivers is a quiet reliability fix: parallel tool calls are now fault-isolated. Before this, if you fired off a batch of tool calls and one Bash command in that batch failed, it could cancel the rest of the batch along with it. Now each call returns its own result independently. One failure doesn't drag down its neighbors. If you lean on batched tool runs, and on a Claude Code podcast I'd bet you do, that's a real footgun gone. It's all in the Claude Code changelog.

There's also a naming correction from the release right before it, version 2.1.160. The trigger keyword for Dynamic Workflows changed. The word "workflow" no longer kicks off a dynamic-workflow run. The trigger is now the word "ultracode," highlighted in violet right there in the prompt input. Asking for one in your own plain words still works, but if you'd wired the word "workflow" into muscle memory or into a script, swap it over to "ultracode."

A few more from yesterday worth a flag. The mcp commands that list, get, and add servers no longer print your secrets out loud: environment-variable references stay unexpanded, and credential headers and any secrets in a URL get redacted in the output. If you script around your mcp config, double-check that your secrets really are hidden now. There were also two worktree fixes, which is well timed given today's main topic. Background workflow agents that spawned in their own worktree had been getting blocked from editing files in that very worktree, and the autofix command for pull requests was wrongly refusing to run inside a worktree. Both fixed. So the next action here is simple: run claude update, confirm you're on the new version, and try kicking off a workflow with that new ultracode keyword.

The bigger story is a billing change with a deadline on it. Starting June fifteenth, Anthropic splits programmatic Claude usage onto its own separate monthly credit pool, billed at standard API list rates. This was announced back on May fourteenth, so it's about twelve days out from today. The part that matters: this hits the Agent SDK, the headless claude command you run with dash-p, Claude Code's GitHub Actions, and third-party apps that authenticate through the Agent SDK. Interactive Claude Code, the kind you type into in your terminal or your IDE, is unaffected, and so are web chat, mobile, and Cowork. If you're driving Claude by hand, nothing changes.

But if you run automation on a subscription plan, it changes a lot. Reportedly, the credit amounts come out to twenty dollars a month on Pro, a hundred on Max five-x, and two hundred on Max twenty-x, per user, and they don't roll over month to month. When the credit runs dry, your requests either route to overflow billing, if you've turned that on, or they just stop until the next cycle. There's no automatic fallback. Reporting also says you may need to claim the credits before the fifteenth, through instructions sent to your account email. So if you run headless jobs in CI, anything on the Agent SDK, or Claude Code Actions, go check that email, estimate your token burn against the per-plan credit, and decide whether to switch on overflow billing so a job doesn't silently halt mid-run. I'm marking those dollar figures as reported, since they come from secondary coverage, but the split itself, and the surfaces it touches, are well established. There's a good rundown at The New Stack.

Two quick ones to close. Plugins now auto-load from your skills directories, so a skill you drop in there registers without any manual setup. And auto mode is now available on Bedrock, Vertex, and Foundry for Opus 4.7 and 4.8, behind an opt-in environment variable. That's the beat for this week.

From one session to several

For the last nine episodes, everything we did, we did by hand, in one session. One Claude, one terminal, one task at a time. Last episode I called cost and evals the last rung of doing everything by hand, and I meant it. This is the episode where we start climbing into Act two, wiring Claude into systems. And the very first rung is small, but it changes how your whole day feels: running several Claude Code sessions at once, in parallel, without them stepping on each other.

The thing that makes that safe is an old, underused git feature called the worktree. So before we touch Claude at all, let's get crisp on what a worktree actually is, because everything else in this episode hangs off it.

What a git worktree really is

Normally a git repository has one working directory. One folder on disk with your files, one branch checked out at a time. If you want to jump from your feature branch over to main, you stash or commit, you switch, and your files change underneath you. One tree, one branch, strictly serial. That's the model you've lived in for years.

A worktree breaks that one-to-one. The official git worktree documentation describes it as checking out more than one branch at a time, by attaching several working directories to the same repository. So you get one shared git history, the commits, the refs, the remotes, all of it living in a single place, and several separate folders on disk, each with its own checked-out branch, its own HEAD, its own staging area.

Picture it as one library with several reading rooms. The books, the catalog, the shelves, all of that is the shared git store. But each reading room has its own desk with its own papers spread across it. What you do at one desk doesn't shuffle the papers on another. Make a commit in one worktree and it shows up instantly in another worktree's git log, because the history is shared, but the messy working files stay exactly where they are, room by room.

Under the hood, git makes this work by giving each linked worktree a small private directory of its own inside the repository's git folder, holding that worktree's HEAD and index, while everything else points back to the one shared object store. You don't need to manage any of that by hand. The point to keep is the split: history and objects are shared, the checked-out branch and the working files and the staging area are private to each worktree.

Now here's the one constraint that drives the entire workflow, and the one you will trip over first. A branch can only be checked out in one worktree at a time. The docs say it plainly: add refuses to create a new worktree on a branch that's already checked out somewhere else, unless you force it. So you cannot point two worktrees at main and run two Claudes on it. Each parallel session needs its own branch. Hold onto that one, it's the rule sitting underneath all the others today.

The handful of commands you actually need

The command surface here is small, which is part of why worktrees are underused, people assume it's more complicated than it is. The command you'll use constantly is git worktree add. Hand it a path and it creates a second working directory there on disk.

If you give it just a path, say git worktree add and then a sibling folder called hotfix, git quietly creates and checks out a brand new branch named after that last folder, hotfix. Convenient, but it's easy to forget that git just invented a branch for you, so be aware of it.

More often you'll want to be explicit. Give add a path and an existing branch name, and it checks that branch out into the new folder. Or pass the dash-b flag with a new branch name and a path, and it creates that branch fresh and checks it out for you. Dash-b refuses if the branch already exists, which is a feature, not an annoyance, it stops you from clobbering work you forgot was there. There are a couple of cousins too: a detach option that gives you a worktree sitting on a specific commit with no branch at all, handy for a throwaway experiment, and an orphan option that starts a worktree on a brand new empty branch.

The rest you'll use only occasionally. git worktree list shows every worktree you've got open, its path, and what's checked out where, which is the first thing to run when you lose track. git worktree remove tears one down, but only if it's clean, you have to force it otherwise so you don't lose work by accident. git worktree prune tidies up the internal bookkeeping for any worktree whose folder you deleted by hand instead of removing properly, which, let's be honest, you will absolutely do at some point. And there are lock, move, and repair commands for the rarer cases, like a worktree that lives on a network drive you don't want git to touch, or one you relocated and need to reconnect.

Where should these worktree folders live? There are two sane conventions. One, put them as siblings right next to your repo, so a folder called my-app gets a neighbor called my-app-feature-auth. Two, keep them all in one dedicated subfolder. Claude Code's own default, which we're about to get to, tucks them under a hidden worktrees folder at the root of your repo.

But there's a trap here that's worth stopping on, because it's a miserable afternoon if you hit it. Do not nest a worktree inside your repository's own working tree unless you've gitignored it. If a worktree folder lives somewhere your tools watch and index, your file watcher picks it up, your test globs start matching it, your type checker walks down into it, your bundler tries to compile it, and the whole thing shows up as a pile of untracked files in your main checkout. The fix Anthropic recommends is exactly one line: add that worktrees folder to your gitignore, so its contents never leak into your main checkout. We'll do that in the setup in a minute.

Claude Code does this natively now

Here's the recent piece of news that actually reshapes the workflow. Claude Code grew built-in worktree support. You used to wire all of this up by hand with raw git; now there's a flag that does the common case for you. Boris Cherny, who created Claude Code, announced it like this: agents can now run in parallel without interfering with each other, each agent gets its own worktree and works independently. The desktop app had had it for a while, and now it's in the CLI too.

So there are two layers to keep in your head. The raw git commands, which you'll still reach for when you need a specific branch or a folder in an unusual place, and Claude's own flag, which automates the everyday case.

That flag is dash-dash-worktree, or dash-w for short. You run claude dash-w and a name, say feature-auth, and Claude creates a worktree and starts a session inside it, all in one move. Open a second terminal tab, run claude dash-w bugfix and a number, and that's your second isolated session up and running. Leave the name off entirely and Claude makes one up for you, something like bright-running-fox.

By default it does three thoughtful things. It puts the worktree under that hidden worktrees folder at your repo root. It names the branch worktree-something, after the name you handed it. And, importantly, it branches from the remote's default branch, origin's HEAD, so each new session starts from a clean tree that matches the remote rather than from whatever half-finished state your main checkout happens to be in. If there's no remote, or the fetch fails, it falls back to your local HEAD.

You can change that base if you want. There's a worktree setting called baseRef, and it takes one of two values, fresh or head. Set it to head and your new worktrees carry your unpushed commits and your in-progress branch state along with them, which is exactly what you want when you're isolating an agent that has to build on work you haven't pushed up yet. The docs are clear that it only accepts those two values, fresh or head, not an arbitrary branch name.

Here's one genuinely nice trick. You can spin a worktree straight off a pull request. Pass the PR number with a hash sign in front of it, or paste a full GitHub PR URL, and Claude fetches that pull request's head and drops you into a worktree named after it. That's great for reviewing or fixing up someone's open PR in isolation, without disturbing a single thing in your own work.

There's one gotcha that will bite you the very first time, so let me save you the confusion. Before you can use the worktree flag in a directory, you have to accept the workspace trust dialog by running plain claude once in that folder. Skip that step and the worktree flag just errors out and tells you to run claude first, and yes, that includes when you combine it with headless mode. So the first thing you do in a fresh repo is run claude once, accept trust, and then start using worktrees.

And you don't have to decide any of this up front, by the way. Mid-session you can simply tell Claude to go work in a worktree, and it'll create one for you using an internal tool. Once it's in one, you can have it hop over to another worktree under that folder, and the one it just left stays right there on disk, untouched, exactly where you can come back to it later.

Carrying your config across, and isolating subagents

Here's a problem you'll run into within the first few minutes. A worktree is a fresh checkout, so it does not contain your untracked files. Your environment file, the local env file with your database URL and your API keys in it, is gitignored, which means it simply isn't there. Your shiny new session boots up with no config and falls flat on its face.

The fix is a small file at your project root called worktreeinclude. You list patterns in it using gitignore syntax, your env files, a secrets config, whatever your app needs, and Claude copies just those files into each new worktree as it creates it. The safety detail is nice: it only copies files that both match a pattern and are gitignored. Tracked files are never duplicated, so you're not making redundant copies of things git already manages for you. This works for the worktree flag, for subagent worktrees, and for the desktop app's parallel sessions alike. One footnote: if you're on a non-git version control system and using a custom creation hook to make your worktrees, that include file is skipped, and you copy the config inside your hook script instead.

That subagent piece ties straight back to the subagents episode from Act one. Remember, a subagent is a fresh Claude that does a self-contained job in its own context window and hands back just a summary. Now you can give each one its own worktree, so their parallel edits don't collide with each other or with your main session. Just ask Claude to use worktrees for its agents, or make it permanent on a custom subagent by adding an isolation setting of worktree to that subagent's frontmatter, the little config block at the top of its definition. Each one gets a temporary worktree that's swept away automatically the moment the subagent finishes without leaving any changes behind.

Which brings up cleanup, and the rules here are worth knowing cold, because leftover worktrees are a classic way to make a mess of your repo. If a session ends with nothing worth saving, no uncommitted changes, no untracked files, no new commits, Claude removes the worktree and its branch for you. If there's anything worth keeping, it prompts you, keep or remove, and choosing remove throws those changes away. The one case to really watch: if you ran the worktree flag in headless mode, non-interactively, there's no exit prompt at all, so nothing gets cleaned up automatically and you remove it yourself with git worktree remove. Background and subagent worktrees get swept later once they're stale and clean, but the ones you created on purpose with the flag are never auto-deleted. That last part is by design. Your explicit worktrees are yours to keep until you say otherwise.

Running several at once: what's shared, what's not

Okay. The actual parallel workflow. You open a few terminal tabs, or tmux panes, or iTerm splits, and you run a Claude in each one, one per worktree. Each is fully independent: its own context window, its own CLAUDE.md load, its own slash-clear to reset between tasks. They don't share memory, they don't see each other's conversations, they don't know the others exist.

Let me make that concrete with a scene you'll recognize. Say you've got two independent jobs this morning: add Google sign-in to your app, and fix a bug where dates render in the wrong timezone. They touch different files, the auth flow on one side and a date helper on the other, so they're a clean candidate to run side by side. Tab one gets a worktree on a feature-auth branch and a Claude told to implement the sign-in from your plan and run the tests. Tab two gets a worktree on a bugfix branch and a Claude told to find and fix the timezone bug. Both run at once, each in its own folder, each on its own branch, each with its own dev server on its own port. Neither one can see or clobber the other's files. Forty minutes later you've got two branches and two pull requests, and you spent that time reviewing instead of sitting there waiting on a single session. That's the whole promise, and when the work partitions this cleanly, it genuinely delivers on it.

So draw the line clearly in your head, because getting this line wrong is where the pain comes from. What's shared across all your worktrees is the git layer: the object store, the history, the refs, the remotes, even your stashes. Commit in one and the others can see that commit in their log. What's isolated, separate on disk per worktree, is basically everything else: the working files, the checked-out branch, the staging area, and, crucially, everything untracked. That means a separate node_modules folder in each, separate env files, separate build output, separate caches, separate dev-server processes, and the ports those servers grab.

That last part, the untracked stuff being separate per worktree, is exactly where the collisions live. So let me walk you through the three you will actually hit, in order of how often they bite.

Collision one: dependencies

Each worktree is a clean checkout with no installed dependencies in it. So you install per worktree, and that costs time and disk, multiplied by however many worktrees you're running. Four worktrees means four installs.

There are a few ways people handle this. The simplest is to just install in each one, fully isolated and fully correct, but slow and heavy on disk. Some tooling symlinks a single shared dependencies folder into each worktree instead; an open-source app called Parallel Code does exactly that. It's fast, but it breaks the moment two of your branches need different versions of the same dependency. If you use pnpm, you're in a good spot here, because its global content-addressable store means each install is mostly just hard-links pulled from one shared store, so per-worktree installs get cheap without the version-skew risk that the symlink approach carries.

And here's the related pitfall, the one community guides have started calling the lockfile war. Two agents, on two branches, both touch the lockfile, your package lock or your pnpm lock, and when you go to integrate the work, you've got a merge conflict in the one file you least want to resolve by hand. File that away, because it comes back when we talk about how to partition work so this doesn't happen.

Collision two: ports

This one is almost guaranteed on a Next.js app. Two worktrees, both running the dev server, both trying to bind port three thousand. The second one either fails outright or quietly grabs some other port, and now you're sitting there staring at the wrong build, wondering why on earth your change isn't showing up.

The fix is to give each worktree its own port. With Next.js you run the dev command with the dash-p flag and a number, so worktree one stays on three thousand, worktree two goes to three thousand and one, and so on up the line. The PORT environment variable works too.

But here's the trap hiding inside the trap, and it's a good one to know because it eats real time. You cannot set that PORT value in your local env file for the dev server. The reason is timing: Next.js boots its HTTP server and binds the port before it loads your env files, so a PORT line sitting in your local env file is silently ignored. People lose an hour to this and feel a little crazy by the end of it. Set the port on the command line instead, or bake it right into the dev script in your package file, one port per worktree. The same logic applies to anything else that binds a port, your Storybook, a mock API, a websocket server. Give each worktree its own lane and label it.

Collision three: the database

This is the deep one, because it's the collision that worktrees genuinely cannot save you from. Worktrees isolate your filesystem checkout. They do not isolate the world. If both of your sessions point at the same dev Postgres, and both agents decide it's time to run migrations, they collide, and they collide ugly: schema drift, half-applied migrations, two migration files stamped with clashing timestamps, one agent's seed data stomping all over the other's test fixtures.

The cures here are heavier than a single flag. A separate database, or at the very least a separate schema, per worktree. A Dockerized database per worktree, which is one of the things Parallel Code offers, sandboxing through per-project Dockerfiles. Or, honestly, the cure that's usually the right one: don't parallelize work that touches shared schema in the first place. The database is the cleanest example of shared external state, and it's worth widening the lens right here, because it's not just the database. Redis, your job queues, third-party sandbox keys that carry their own rate limits, an upload bucket, anything your env file points at is a shared backing service that two worktrees will both happily reach into at the same time. So say it back to yourself: worktrees give you filesystem isolation, not world isolation. That sentence will save you a bad afternoon.

Bringing the parallel work back together

Each worktree is on its own branch, so integration is just ordinary git, nothing exotic. Push each branch, open a pull request, or merge and rebase locally. Anthropic's documented flow is to ask Claude to commit with a descriptive message and open a PR, and they recommend installing the GitHub CLI, the gh tool, so those requests are authenticated and don't run into rate limits, all per their best practices guide. One nice touch: after the pull request is created, your session gets linked to it, so you can come back later by launching Claude straight from that PR number.

Now the conflict reality, because I don't want to oversell this. Worktree branches diverge like any other branches do. If two of your agents edited the same files, you get genuine merge conflicts that a human, or another Claude session, has to sit down and reconcile. That's the lockfile war again, plus any shared module that both features happened to touch. And this is really the whole game: the value of worktrees evaporates the instant you fan out tasks that overlap on the same files. Anthropic says it flatly in their guidance on the related team feature, two teammates editing the same file leads to overwrites, so break the work up so each one owns a different set of files. The exact same rule applies here. Partition by file ownership, or honestly, don't partition at all.

One concrete tactic for the merge itself. Bring in the smallest, most foundational branch first. Merge it, rebase the others on top of the new main, resolve the conflicts once, and repeat down the line. It beats trying to land four divergent branches at the same time and resolving the same conflict four separate times in four different orders.

When not to fan out at all

This is the judgment call that separates somebody who just looks busy from somebody who's actually getting more done. Parallelism is not free, and more agents is not automatically more output. So let's talk about when to keep your hands off the worktree flag entirely.

Start with the tasks that simply lose when you parallelize them. Sequential work, same-file edits, anything with a lot of shared dependencies between the steps. Anthropic's own line is that for those, a single session, or subagents inside one session, are more effective than parallel teammates. If the steps depend on each other's output, running them side by side just produces garbage faster, and then you have to redo it.

Then there's the real ceiling, and it isn't Claude at all. It's you, the reviewer. The community consensus settling in around mid-2026 is that a single developer can run somewhere around four to eight concurrent worktrees reliably, and above that you're bottlenecked on review, not on the model, per a thorough worktrees guide from Claude Directory. You, the human, are the serial resource in this system. Parallelism that outruns your ability to actually review the output doesn't hand you throughput, it hands you a backlog of un-reviewed branches and a comfortable false sense of progress.

And the overhead is real on both ends of the work. You spend time up front carving the task into clean, non-overlapping pieces, and then time on the back end reconciling lockfiles and merges and context-switching between four different diffs that have all gone cold in your head. That coordination and reconciliation can quietly eat the entire speedup you thought you were getting. Anthropic frames it well for the team feature, and it maps straight onto manual worktrees: three focused teammates often outperform five scattered ones, and past a certain point, adding more teammates just doesn't speed the work up proportionally. Diminishing returns set in faster than you'd guess.

And don't forget the bill, which connects straight back to the cost and rate-limit episode. N parallel sessions is roughly N times the token burn, because each session has its own context window chewing through tokens independently of the others. The team feature, which adds inter-agent messaging on top of all this, reportedly runs around seven times the tokens of a standard session when teammates are sitting in plan mode. Plain worktrees are cheaper than that, since there's no chatter between agents, but you're still multiplying your spend by the number of live sessions. And remember that rate limits are per organization, not per session, so four concurrent Claudes are all eating out of the same shared budget at once. Watch it with slash-usage, which breaks the cost down by session and even by skill and subagent, and set your spend limits before you go wide, not after you've blown through them.

So here's the heuristic to actually carry out of this episode. Fan out only when the work cleanly splits into independent, non-overlapping sets of files, and each piece has its own way to verify itself, its own tests or build or screenshot. That's the same give-Claude-a-way-to-check-its-own-work rule we leaned on back in Act one. If you can't draw that clean boundary between the pieces, run one focused session and be honest with yourself about it. Three focused worktrees beat five scattered ones, every single time.

A practical note on how you actually brief these parallel agents, since you are not there to course-correct each one in real time the way you would in a single focused session. Give each worktree a task that's bounded and self-checking. Hand it the plan, point it at the specific files it owns, tell it exactly which command proves the work is done, the test, the build, the type check, and tell it to commit in small steps with clear messages rather than one giant commit at the very end. Small frequent commits keep each branch easy to reason about when you come back to review it cold an hour later, and they make the eventual rebase far less painful. The discipline you built up in Act one around planning and verification matters more here, not less, precisely because you've taken your hands off the wheel of three sessions at the same time.

The workflow, start to finish

Let me put the whole thing together as one motion so it sticks. First, the one-time setup in a fresh repo. Run plain claude once to accept the trust dialog. Add the worktrees folder to your gitignore so it never pollutes your main checkout. And drop a worktreeinclude file at the root, listing your env files, so each worktree boots up with its config already in place instead of falling over.

Then the parallel part itself. In tab one, run claude dash-w feature-auth, and tell it to implement the feature and run the test suite, with its dev server on port three thousand. In tab two, run claude dash-w bugfix and the issue number, with its dev server on three thousand and one so the two don't collide. Each session commits on its own branch and opens its own pull request. You integrate the smallest branch first and rebase the rest on top. And you clean up at the end with git worktree list to see what's still open, git worktree remove for the ones you're done with, and git worktree prune to sweep up the bookkeeping.

Now the one pitfall to burn into memory, because there's a good chance you hit it this week. You launch two worktrees, both of them run the dev server, and the second one silently grabs the wrong port, or serves the wrong build. You'll recognize it by checking what's listening on port three thousand and finding two processes fighting over it, or by Next.js cheerfully announcing it jumped to some port you never asked for. The fix is to assign your ports explicitly, remembering that setting that port value in your local env file does nothing at all for the dev server. And the deeper, nastier version of that same pitfall is the database: two worktrees migrating the same dev database straight into corruption. The cure there isn't a flag at all, it's a database per worktree, or simply not parallelizing schema work in the first place.

One more thing worth knowing before you go wide: you don't have to babysit four terminal tabs by eyeball. The desktop app creates a worktree for every new session automatically and lets you manage them all visually in one place, and Claude Code's background agents let you watch several running sessions from a single screen instead of constantly flipping between separate terminals. There's also a small ecosystem growing up around this. That Parallel Code app I mentioned dispatches agents each into their own branch and worktree and gives you a built-in diff viewer to review the work and merge the wins, and there are command-line wrappers, like one called Worktrunk, that aim to make worktrees, in their own words, as easy as branches. Treat the third-party tools as leads worth trying rather than gospel. The built-in flag and the raw git commands underneath it are the load-bearing parts you actually need to understand.

Where this goes next

Everything we did today was manual and human-supervised. You opened the tabs yourself, you assigned the work yourself, you reviewed the diffs and you did the merges. The next rung up the ladder automates the coordination itself: a lead session that spawns teammates, hands them a shared task list, and lets them message each other to divide up the work. That's the orchestrator pattern, and it's where we go next. Worktrees are the foundation it stands on, they handle the file isolation underneath, and the orchestrator adds the coordination on top of that. Here's the quick contrast to hold until then: the subagents we met back in Act one report back to one main agent and never talk to each other, while orchestrated teammates share a task list and message each other directly. That's a whole episode of its own. For today, you've got the thing that makes all of it safe in the first place: several Claudes, several worktrees, one shared repo, and nobody stepping on anybody.