All pages

Many agents at once · Lesson 1.1 · 12 min · Free

One worktree per agent

Separate checkouts so parallel agents never edit the same files.

Listen

After this lesson you can run two or more agents on one project at the same time without their edits, builds or commits colliding, because each one works in its own checkout on its own branch.

Time: 12 minutes · Works on: macOS app. Linux, Windows and the cloud workspace reach worktrees through the agent's worktree_* tools.

Why one folder can't hold two agents

An agent treats the folder it works in as its own. It edits a file, runs the build, reads the failures and edits again. That loop assumes nothing else is changing the files between steps.

Put a second agent in the same folder and the assumption breaks in ways that are hard to see:

  • Edits collide. Both agents touch the same file. One rewrites a function the other is halfway through changing, and the second agent's next edit is based on text that is no longer there.
  • Builds lie. Agent A runs the tests while agent B is mid-edit. A sees failures it didn't cause and starts "fixing" B's unfinished work.
  • Commits mix. Agent A runs git add . and commits B's half-done change under A's message. Now neither branch tells a clean story.
  • Nobody can tell whose change is whose. When something breaks, you can't revert one agent's work without reverting the other's.

The fix isn't for the agents to be more careful. It's to give each one a separate checkout, so the only shared thing is the git history they both start from.

The rule: one agent, one branch, one checkout

A git worktree is a second checkout of the same repository, in its own folder, on its own branch. It shares the .git directory, so it's cheap to make. The Worktrees lesson covers the mechanics. This lesson is about using them as the unit of parallel work.

Hold to three rules:

  1. Every agent gets its own worktree. The primary checkout is yours. Agents work beside it, never in it.
  2. Every worktree gets one task. A branch named agent/search-filter that also fixes the login bug is two tasks, and you'll review them as one.
  3. The branch is the deliverable. An agent is done when its branch is committed and ready to review, not when it says it's done.

Split the work so the branches don't fight

Separate checkouts stop agents from trampling each other while they work. They don't stop the merge from being painful later. If two agents both rewrite router.ts, you'll resolve that conflict by hand.

So split by area, not just by task. Before you start two agents, ask which files each task will touch. If the answer overlaps heavily, run them one after the other instead, or make one depend on the other. A good parallel pair looks like this:

Agent Branch Touches
A agent/search-filter src/search/, its tests
B agent/export-csv src/export/, its tests, one menu entry

They share one menu file, and that's a one-line conflict at worst. Two agents both "improving error handling" across the codebase would collide everywhere.

Mind the things a checkout doesn't separate

A worktree separates files. It doesn't separate everything else on your Mac:

  • Ports. Two dev servers both want port 3000. Give each worktree its own port, or let only one run a server at a time.
  • Shared services. Two agents running migrations against one local database will fight over it. Use separate databases or keep one agent off it.
  • Global installs. An agent that runs brew install or edits a global config changes things for every checkout.

Put these constraints in each agent's brief. "Run the dev server on port 3101" is a one-line instruction that saves an hour of confusion.

A worked example

You want a search filter and a CSV export, and you have an afternoon.

  1. You create two worktrees, agent/search-filter and agent/export-csv, both branching from main.
  2. You open a tab in each and start Claude Code there, with a brief that names the folder it owns, the port to use and the test command that defines done.
  3. While both run, you stay in the primary checkout, free to read code or review.
  4. The search filter finishes first. You read its diff, open a pull request from its worktree and merge it.
  5. The export branch now trails main by one merge. You ask its agent to rebase on main and rerun the tests before you review it.
  6. You merge the second pull request and remove both worktrees.

Neither agent ever saw the other's half-finished files.

Do it in TRMNLY

TRMNLY ties each terminal tab to a worktree, and points its own tools at the worktree you're in. That's what makes a worktree per agent cheap to keep straight.

  1. Create one worktree per agent. Select the project, then press ⌃⌘N (or click the worktree selector pill at the top of the left sidebar and choose New Worktree…). Enter a Branch name such as agent/search-filter, leave Base ref (optional) empty to branch from HEAD, and click Create. Repeat for agent/export-csv. TRMNLY copies untracked files such as .env and node_modules into each new folder, so an agent can run the build without a fresh install. Which files are copied is under Copied env files in Manage Worktrees….
  2. Open a tab in each worktree. Switch with the selector or ⌃⌘1–⌃⌘9. Each worktree shows only its own tabs, so the tab list itself tells you which agent you're looking at. In the new tab, run echo $TRMNLY_WORKTREE_BRANCH and pwd to confirm the shell is in the worktree's folder.
  3. Start Claude Code in each tab. Run claude in each worktree's tab and give it its brief. If you've connected Claude Code to TRMNLY (Settings → AI Agent → External MCP clients, then Connect), a session started in a worktree folder has TRMNLY's tools bound to that project and that worktree. Its kanban_add lands on the project's board, and its bash runs in its own checkout, whichever window you're looking at.
  4. Keep Claude Code on TRMNLY's worktree tools. Claude Code has its own worktree tool that doesn't know about projects. Tell it to use worktree_create and worktree_switch instead. If it already made one another way, worktree_adopt registers it with the project.
  5. Know what the sidebar agent follows. The Agent tab's file, git_* and bash tools run in the active worktree, and switching worktrees mid-turn moves them. That's right when you work with one agent at a time. For agents that must keep working while you switch around, use a Claude Code pane per worktree as above, or let TRMNLY start them pinned to their own worktrees with a race or a fleet (the next lessons).
  6. Name each pane. In each agent's tab, run trmnly set-title "Search filter" and trmnly set-description "Adding the filter UI; next, tests". The sidebar row shows the title and description, so you can tell the agents apart at a glance. Make the first word differ between panes, because the sidebar cuts long titles from the right.
  7. Give each worktree its own port. Ask the sidebar agent "Is port 3000 free?" It calls ports_check, which says who holds the port and suggests the next free one. Put that port in the second agent's brief. The Ports lesson shows how to reserve ports for a project ahead of time.
  8. Watch the checkouts, not just the chat. Click the worktree selector. Each row shows its branch, a * if it has uncommitted changes, and how many tabs it has open. A worktree that has gone quiet with no * and no commits is an agent worth checking on.
  9. Land each branch on its own. When an agent's branch is committed, click the selector and choose Open PR…. After merging, open Manage Worktrees… and use Merge PR & Clean Up…, or remove the worktree from its row. Removing a worktree deletes its folder, so make sure anything you want is committed or pushed.

Check yourself

  • Two worktrees each have a tab running an agent, and pwd in each prints a different folder.
  • You can say which files each agent will touch, and the sets barely overlap.
  • An edit one agent made doesn't appear in the other worktree.
  • You know why switching worktrees moves the Agent tab's tools but not a Claude Code session started in a worktree folder.
  • Each branch reached its own pull request.

Go further