Why every chat gets its own git worktree

Two coding agents working in the same folder will edit the same files and break each other's builds. A git worktree gives each one its own full checkout on its own branch, from the same repository. That's why every Shuriken chat, except one, gets its own worktree.

Two agents, one folder#

We tried the simple way first. Two Claude Code sessions, one repo, one folder. It went about as well as two people typing on one keyboard.

Agent A renames a function. Agent B, halfway through its own task, runs the tests. They fail, for a reason B didn't cause. B "fixes" them by changing the file A was editing. A comes back, sees its change gone, and puts it back. Meanwhile the dev server is hot-reloading a half-edited file, and somebody ran npm install with a different lockfile.

Nobody did anything wrong. They just shared a desk.

What a worktree is#

Git has had an answer to this for years. In git's own words, git worktree lets you "manage multiple working trees attached to the same repository" (git documentation).

In plain terms: a worktree is another folder with a full checkout of your project, on its own branch. All the worktrees share one git history, so creating one is quick and nothing has to be cloned. But each has its own files, so an edit in one is invisible to the others until you merge it.

Git also protects you here. By default, it refuses to check out a branch in a new worktree when another worktree already has it checked out. Two worktrees can't quietly fight over one branch.

How Shuriken uses them#

Every new chat gets its own branch in its own worktree and works alone. Its tests run against its own files, and another agent's half-finished edit never shows up in its build.

The Main chat is the exception. Each project has one chat that works on your own branch, in your own folder. It's for the quick stuff: a typo, a config tweak, "rename this", where you want the change right now in the folder your editor already has open.

You can look inside any chat's worktree by opening it in your editor or terminal from the chat with Open in: VS Code, Cursor, Zed, the JetBrains IDEs, Xcode, Terminal, iTerm, Ghostty and more, 44 targets in all. And a chat can move. Choose Run on… to run it on another of your computers or a server: it stays the same chat, and that computer gets the repo if it doesn't have it yet.

So you can start five chats on five tasks, and none of them knows the others exist. That's what parallel agents means in Shuriken.

The cost#

Worktrees aren't free, and we'd rather tell you now.

The first cost is disk. Git history is shared, but each worktree has a full copy of your files. Then your build adds its own: node_modules, a target folder, build output. For a big JavaScript or Rust project that can add up quickly. Shuriken sets no cap on how many chats you run. Your disk, your memory and your plans set the real one.

The second is your limits. Five agents use your plan five times as fast, so if you run several at once you'll reach your limits sooner. Source switching moves chats to another of your accounts when one runs low, and the setup for several agents at once is in our guide on running Claude Code agents in parallel.

Getting the work back: Finish#

Five branches are only useful if the work ends up in one place. That's what Finish does.

One click runs your checks, the ones you list in shuriken.json, such as your type check and your tests. Then it rebases and squash-merges the chat's branch, or opens a pull request with auto-merge on, if you'd rather review on GitHub. Finish never closes a chat over work that hasn't been merged. The whole flow is in Finish: checks, rebase and merge in one click.

Try Shuriken and give each chat its own desk.