Git Worktrees for Parallel Agent Workflows
By MobileVibe Team · August 5, 2026 · 12 min read
Git Worktrees for Parallel Agent Workflows
Quick answer
Git worktrees let you check out multiple branches simultaneously in separate directories, so you can run several AI coding agents in parallel without them colliding. Each worktree becomes an isolated “lane” where one agent works on one feature or fix, and you can monitor, approve, and merge their work from your phone without switching branches or stashing changes.
Key takeaways
- Worktrees = parallel agent lanes: each worktree is a separate directory tied to a branch, so agents never fight over the same working copy
- One conversation per worktree: MobileVibe conversations are folder-scoped; each worktree gets its own agent session you can monitor and approve independently
- Mobile-friendly review: approve diffs, check status, and merge from your phone while agents keep running on your desktop
- Avoid merge chaos: worktrees make it obvious which agent is working where, reducing accidental conflicts and stale-session confusion
- Scale to many agents: run five, ten, or more agents across worktrees without filesystem gymnastics or constant branch switching
Why Agents Need Isolated Branches
When you direct an AI coding agent—Claude, Codex, Cursor, or Windsurf—you’re asking it to read files, write code, run tests, and commit changes. If you start a second agent in the same directory while the first is still working, they’ll collide: both will try to modify the same files, stage overlapping changes, and leave your working copy in an ambiguous state. You can’t easily tell which edits belong to which agent, and approving one agent’s diff becomes a mess of unrelated hunks.
The traditional solution is to stop the first agent, stash or commit its work, switch branches, and start the second agent. That’s fine for sequential work, but it breaks down when you want agents running in parallel—one refactoring the API layer, another fixing a bug in the UI, a third writing tests. Git worktrees for agents solve this by giving each agent its own directory and branch, all sharing the same .git repository. You can start an agent in ~/project/main, another in ~/project/feature-auth, and a third in ~/project/fix-typo, and they’ll never see each other’s uncommitted changes.
From a mobile-control perspective, worktrees make your agent inbox clear: each conversation is tied to a folder, so you know exactly which agent is working on which feature. You can approve the auth agent’s diff, let the typo fix keep running, and pause the refactor until you’re back at a real keyboard—all without branch-switching gymnastics.
Creating and Managing Worktrees for Agent Lanes
Start with a repository that has at least one commit. To create a new worktree for a feature branch:
git worktree add ../project-feature-auth -b feature-auth
This creates a new directory ../project-feature-auth checked out to a new branch feature-auth. The worktree shares the same .git repository as your main checkout, so commits, branches, and remotes are all synchronized. You can also check out an existing branch:
git worktree add ../project-fix-typo fix-typo
List all worktrees:
git worktree list
You’ll see each worktree’s path, branch, and commit. When you’re done with a worktree—agent finished, branch merged—remove it:
git worktree remove ../project-feature-auth
Or delete the directory and run git worktree prune to clean up metadata.
Naming convention: use a consistent pattern like ~/project/main, ~/project/feat-X, ~/project/fix-Y. This makes it obvious which worktree is which when you’re scanning your MobileVibe dashboard from a phone. Avoid deep nesting or cryptic abbreviations; you’ll thank yourself when you’re triaging five agents at once.
Agent setup per worktree: each worktree is a separate folder, so you start an agent session there just like you would in any project directory. For Claude CLI, cd ../project-feature-auth && claude. For Codex CLI, cd ../project-feature-auth && codex. For Cursor or Windsurf, open that folder in the IDE and start a chat. MobileVibe’s Desktop Connector sees each worktree as a distinct project folder, so each agent session gets its own conversation entry in your mobile dashboard.
Keeping Agent Sessions Separate Across Worktrees
Because MobileVibe conversations are folder-scoped, each worktree automatically gets its own conversation. If you start Claude in ~/project/main and Codex in ~/project/feat-api, you’ll see two separate conversations in your mobile inbox. This isolation is the whole point: you can check the status of the API refactor without accidentally approving the main-branch agent’s unrelated diff.
Session persistence: agent sessions keep running on your desktop as long as the Desktop Connector is online and the agent process hasn’t exited. If you close your phone or switch apps, the agent keeps working. When you reopen MobileVibe on your phone, you’ll see the latest state—waiting for approval, still working, or finished. If the agent hit a quota or auth issue, you’ll see that too, and you can re-auth or adjust limits from mobile if the agent supports it.
Cross-surface resume: Claude IDE and CLI can share the native Claude conversation store, so you can start a conversation in the CLI (in one worktree), approve a step from your phone, and later open that same conversation in Claude Desktop (pointed at the same worktree folder). Codex has a separate IDE extension and MobileVibe’s headless codex-cli; moving history between them may require copying or forking the conversation. Cursor and Windsurf are separate host apps, not VS Code aliases, so full history enumeration or Claude-like surface switching should not be assumed—treat each surface as its own lane unless you’re explicitly copying conversation context.
Avoiding confusion: if you have five worktrees and five agents, label your branches clearly and use MobileVibe’s conversation titles (which default to the folder name) to stay oriented. When you’re on your phone, you want to see “feat-auth: waiting for approval” and “fix-typo: still working,” not “project-1” and “project-2.”
Approving and Merging Agent Work from Mobile
The everyday moment: you’re away from your desk, and an agent in ~/project/feat-auth needs approval to commit a batch of changes. You open MobileVibe on your phone, see the conversation, review the diff, and approve. The agent commits and continues. Later, you’re ready to merge that feature into main. From your phone, you can:
- Check the final diff: open the conversation, see the last commit or set of commits the agent made.
- Decide if it’s safe to merge: if the changes are small and the tests passed, you might merge from mobile. If the diff is large or touches critical code, you’ll want a real desktop review.
- Merge from terminal or IDE: if you’re comfortable, you can use MobileVibe’s terminal access (where supported) to
git checkout main && git merge feat-authfrom your phone. Or you can wait until you’re back at your desktop and merge there.
Auto-approve controls: some agents (notably Claude CLI) support auto-approve modes where the agent can commit without asking. If you trust the agent and the worktree is isolated, you can enable auto-approve for that conversation and let it run unattended. Just be aware that you’re giving the agent commit access; review the final diff before merging into main.
Push and PR workflow: after the agent finishes, you’ll typically push the worktree’s branch (git push origin feat-auth) and open a pull request. You can do this from your phone’s browser or a mobile GitHub app. Review the PR diff, request changes if needed, and merge when ready. The worktree stays around until you explicitly remove it, so you can always go back and make tweaks.
Monitoring Multiple Agents Across Worktrees
Your MobileVibe dashboard becomes an inbox of agent lanes: each worktree is a conversation, each conversation shows its current state. You’ll see:
- Waiting for approval: agent hit a checkpoint and needs your OK to proceed.
- Still working: agent is running, no input needed yet.
- Blocked: agent hit a quota, auth issue, or error it can’t resolve.
- Finished: agent completed its task and is idle.
Push and email notifications: MobileVibe can send push notifications (where supported) or email alerts when an agent needs attention. You’ll get a message like “Claude in feat-auth needs approval” and can tap through to review. This is especially useful when you’re running agents overnight or during the day while you’re in meetings.
Parallel progress: because each agent is in its own worktree, you can let them all run at once. One agent might be refactoring the API layer (a long, multi-step task), another fixing a typo (quick, auto-approved), and a third writing tests (medium complexity, occasional approval). You can check in on each from your phone, approve the quick ones, and let the long one keep running until you’re ready to review its final diff.
Resource limits: your desktop has finite CPU and memory. Running ten agents at once might slow things down, especially if they’re all running tests or compiling code. Monitor your desktop’s load and adjust how many agents you run in parallel. MobileVibe doesn’t impose a hard limit, but your machine will.
Common Pitfalls: Merge Conflicts and Stale Sessions
Merge conflicts: if two agents modify the same file in different worktrees, you’ll get a conflict when you try to merge their branches. This is normal Git behavior, not a MobileVibe issue. To minimize conflicts:
- Assign agents to different areas: one agent works on the API layer, another on the UI, a third on tests. If they touch the same files, they’re more likely to conflict.
- Merge frequently: don’t let feature branches diverge for weeks. Merge
maininto your feature branches regularly to catch conflicts early. - Review diffs before merging: if you see overlapping changes, resolve them on your desktop where you have a real diff tool and IDE.
Stale sessions: if you leave an agent running in a worktree for days, its branch might fall behind main. When you finally merge, you’ll have a large diff and potential conflicts. To avoid this:
- Set time limits: if an agent hasn’t finished in a reasonable time (hours, not days), pause it and review what it’s done so far.
- Rebase or merge
mainregularly: keep feature branches up to date so merges are small and predictable. - Clean up finished worktrees: once a branch is merged, remove the worktree. Don’t let old directories pile up.
Accidental cross-worktree edits: if you manually edit files in one worktree and forget which branch you’re on, you might commit to the wrong branch. Worktrees make this less likely (each is a separate directory), but it can still happen if you have multiple terminal tabs open. Use clear terminal prompts that show the current branch, and double-check before committing.
Scaling to Many Agents Without Filesystem Chaos
Once you’re comfortable with git worktrees for agents, you can scale to more ambitious workflows: ten agents working on ten features, each in its own worktree. Here’s how to keep it manageable:
Folder structure: use a flat layout like ~/project/main, ~/project/feat-1, ~/project/feat-2, etc. Avoid deep nesting (~/project/features/auth/worktree-1) because it’s harder to navigate from a phone. If you have many worktrees, group them by prefix: ~/project/feat-auth, ~/project/feat-api, ~/project/fix-typo-1, ~/project/fix-typo-2.
Naming discipline: name branches and worktrees consistently. Use a ticket number or short description: feat-auth-jwt, fix-typo-readme, refactor-api-layer. This makes it obvious what each agent is working on when you’re scanning your mobile dashboard.
Cleanup routine: at the end of each day or week, review your worktrees. Merge finished branches, remove their worktrees, and prune stale metadata (git worktree prune). Don’t let old worktrees accumulate; they clutter your filesystem and make it harder to find the active ones.
Resource monitoring: if you’re running many agents, monitor your desktop’s CPU, memory, and disk I/O. Agents that run tests or compile code can be resource-heavy. If your machine slows down, pause some agents or stagger their start times.
MobileVibe conversation limits: MobileVibe’s free tier has limits on active conversations and desktops. Check current pricing at https://mobilevibe.com/pricing before scaling to dozens of agents. If you hit a limit, you can upgrade or clean up finished conversations.
Backup and sync: worktrees share the same .git repository, so your commits and branches are all in one place. Push branches to a remote regularly so you don’t lose work if your desktop crashes. Worktrees themselves are just directories; if you delete one, you can recreate it from the branch.
FAQ
Can I run the same agent in multiple worktrees at once?
Technically yes—you can start Claude CLI or Codex CLI in two different worktrees simultaneously. Each will be a separate process with its own conversation. However, if both agents are working on related code, they might produce conflicting changes when you try to merge their branches. It’s usually better to run different agents (or the same agent on different tasks) in separate worktrees, rather than duplicating the same agent across worktrees.
How do I resume an agent session after switching worktrees on mobile?
MobileVibe conversations are folder-scoped, so each worktree has its own conversation. If you started an agent in ~/project/feat-auth and then want to check on an agent in ~/project/feat-api, you just open the corresponding conversation in your mobile dashboard. The agent session keeps running on your desktop as long as the Desktop Connector is online and the agent process hasn’t exited. You’re not “switching” the agent between worktrees—you’re switching which conversation you’re viewing on your phone.
What happens if two agents try to merge conflicting changes?
Git will detect the conflict when you try to merge the second branch. You’ll need to resolve the conflict manually—review both agents’ changes, decide which to keep, and commit the resolution. This is normal Git behavior. To minimize conflicts, assign agents to different areas of the codebase and merge branches frequently so they don’t diverge too far from main.
Do I need a separate MobileVibe conversation per worktree?
Yes. Each worktree is a separate folder, and MobileVibe conversations are folder-scoped. When you start an agent in a worktree, it creates a new conversation tied to that folder. This is actually helpful: you can see at a glance which agent is working where, and you won’t accidentally approve the wrong agent’s diff.
How do worktrees help me review agent diffs before merging?
Each worktree is isolated, so the agent’s uncommitted changes and commits are confined to that directory. You can review the diff in that worktree without seeing unrelated changes from other agents. From your phone, you can open the conversation, see the latest diff, and decide whether to approve, request changes, or wait until you’re at a real desktop for a deeper review. Once the agent finishes and you’ve reviewed the final diff, you can merge the worktree’s branch into main with confidence that you’re only merging that agent’s work.
Can I email a conversation to continue an agent in a different worktree?
“Email this conversation” continues the current conversation in the same folder/worktree. If you want to start a new conversation in a different worktree, use “Email this project” and specify the new worktree’s folder path. Be aware that the agent won’t automatically have the history from the first worktree unless you explicitly copy it (e.g., by including a summary in your email prompt). For most workflows, it’s cleaner to keep each worktree’s conversation separate and merge branches when you’re ready to combine the work.
Running multiple AI coding agents in parallel used to mean constant branch switching, stashing, and confusion about which changes belonged to which agent. Git worktrees for agents solve that by giving each agent its own isolated directory and branch, all sharing the same repository. From your phone, you can monitor, approve, and merge agent work across worktrees without ever losing track of who’s doing what. If you’re ready to run agents in parallel and stay in control from anywhere, try MobileVibe free at https://mobilevibe.com and see how worktrees turn agent chaos into a clean, scalable workflow.