Git Worktrees and AI Agents: Running Parallel Development Lanes

Quick answer

Git worktrees let you check out multiple branches simultaneously in separate directories, each with its own working tree but sharing one .git repository. For developers directing AI coding agents, this means you can run several agents in parallel—one per worktree—without branch-switching conflicts, stalled sessions, or merge chaos. Each agent works in its own isolated lane, and you approve, monitor, or merge their output independently.

Key takeaways

• Worktrees enable true parallelism: run Claude on a feature branch, Codex on a bug fix, and another agent on an experiment—all at once, no branch-switching.
• Shared .git, isolated working trees: worktrees share commit history and refs but have separate file states, so agents never collide on disk.
• Agent sessions map cleanly to lanes: each worktree becomes a “conversation” or workstream you can start, pause, approve, and merge independently.
• Mobile oversight scales: with MobileVibe, you can check agent progress, approve changes, and unblock sessions across multiple worktrees from your phone.
• Cleanup is straightforward: remove a worktree when its agent finishes, and the branch/commits remain in the shared repository.

---

Why Worktrees Matter for Agent-Driven Development

When you direct AI coding agents—Claude, Codex, Cursor, or Windsurf—you’re no longer typing every line yourself. You’re starting tasks, reviewing diffs, approving next steps, and merging finished work. The bottleneck shifts from your typing speed to how many agents you can run in parallel and how cleanly you can keep their work separated.

Traditional git workflows assume one working tree per repository. If you want to switch from a feature branch to a hotfix, you git checkout and your entire directory flips to the new branch. Any running agent session in that directory either breaks, gets confused, or forces you to stash/commit incomplete work. You can’t easily run two agents on two branches at the same time without cloning the repository twice—wasteful and awkward.

Git worktrees solve this. A worktree is an additional working directory linked to the same .git folder. You can have main checked out in ~/project, feature/auth in ~/project-auth, and fix/crash in ~/project-crash, all sharing the same commit database, branches, and remotes. Each directory is independent on disk, so an agent working in ~/project-auth never touches files in ~/project-crash. You can run multiple agents simultaneously, each in its own lane, without branch-switching, without conflicts, and without stopping other sessions.

For developers building with agents in 2026, this is the difference between running one task at a time and running three or four agents in parallel, each making progress on a separate branch while you approve, monitor, or ignore them from your phone.

---

Setting Up Isolated Worktrees for Independent Agent Sessions

Creating a worktree is a single git worktree add command. The syntax is:

git worktree add <path> <branch>

Example workflow:

1. You’re in your main repository at ~/myapp on the main branch.

2. You want to start an agent on a new feature. Create a worktree:

   git worktree add ../myapp-feature feature/new-api
   

   Git creates ~/myapp-feature, checks out feature/new-api there, and links it to the shared .git in ~/myapp.

3. Start your agent (Claude, Codex, etc.) in ~/myapp-feature. It sees feature/new-api checked out and works there.

4. Meanwhile, you need a bug fix. Create another worktree:

   git worktree add ../myapp-hotfix fix/null-pointer
   

5. Start a second agent in ~/myapp-hotfix. Now two agents run in parallel, each in its own directory, each on its own branch.

Key points:

• Branch creation: if the branch doesn’t exist, add -b to create it:

  git worktree add -b feature/auth ../myapp-auth
  

• Shared .git: both worktrees reference the same repository. Commits, fetches, and pushes in one worktree are visible in the other (after a git fetch or git pull if needed).

• No branch-switching: you never git checkout in the main directory. Each worktree is pinned to its branch.

• Agent isolation: an agent in myapp-feature can’t accidentally modify files in myapp-hotfix. They’re separate directories.

This setup is perfect for git worktree agents: each agent session maps to one worktree, one branch, one task. You start the agent, it works, you approve or review, and when it’s done, you merge the branch and remove the worktree.

---

Approving and Monitoring Multiple Agents Across Lanes

Once you have agents running in separate worktrees, the challenge becomes keeping track of what needs your attention. An agent in myapp-feature might be waiting for approval. Another in myapp-hotfix might have hit a quota or need re-authentication. A third might be running fine and doesn’t need you at all.

This is where a conversation-first interface matters. Each agent session is a conversation tied to a folder (the worktree directory), an agent (Claude, Codex, etc.), and a surface (CLI, IDE, or headless). Your job is to scan an inbox of what’s blocked, what’s working, and what’s ready to merge.

Practical approval flow:

• Agent needs approval: Claude in myapp-feature proposes a change. You get a notification (push or email). You open the conversation on your phone, review the diff, and approve or reject.
• Agent hit a limit: Codex in myapp-hotfix exhausted its quota. You see the status, decide whether to continue or pause, and either bump the limit or let it wait.
• Agent is running: the third agent in myapp-experiment is still working. You check its progress (files changed, recent output), see it’s on track, and leave it alone.

Auto-approve where supported: if you trust an agent in a low-risk worktree (e.g., a throwaway experiment), you can enable auto-approve for that conversation. The agent proceeds without waiting for you. This is especially useful for parallel lanes where one is exploratory and another is production-critical.

Notifications and email loop: when an agent needs input, you get notified. You can reply via email to continue the conversation or open the MobileVibe app to see the full context. If you’re away from your desktop, you can still unblock the agent, approve the next step, or decide to pause and review later on a real screen.

The key insight: worktrees let you run agents in parallel; a mobile-friendly dashboard lets you manage them in parallel. Without worktrees, you’d be stuck running one agent at a time. Without mobile oversight, you’d be tied to your desk, checking each session manually.

---

Merging Agent Work from Parallel Worktrees

When an agent finishes its task in a worktree, you have a branch with commits ready to merge. The merge process is standard git, but the worktree setup makes it cleaner because you never had to stop other agents or switch branches in your main directory.

Typical merge flow:

1. Agent in ~/myapp-feature finishes. You review the final diff, approve, and the agent commits.

2. In your main repository (~/myapp), you’re still on main. You merge the feature branch:

   git merge feature/new-api
   

   Or, if you prefer a pull request workflow, push the branch and open a PR:

   cd ~/myapp-feature
   git push origin feature/new-api
   

   Then merge via GitHub/GitLab.

3. After merging, you can remove the worktree:

   git worktree remove ../myapp-feature
   

   The branch and commits remain in the repository; only the working directory is deleted.

Conflict resolution: if two agents modified overlapping files in different worktrees, you’ll see merge conflicts when you merge their branches. This is normal git behavior. The worktree setup doesn’t prevent conflicts—it just keeps the agents from stepping on each other while they work. You resolve conflicts during the merge, not during the agent session.

When to merge: you can merge agent work as soon as it’s approved and tested, or batch several branches and merge them together. Worktrees don’t force a specific merge cadence—they just make it easier to have multiple branches in flight at once.

Practical tip: if you’re running many agents, consider a main worktree that stays clean and several feature worktrees that come and go. You merge into main from your desktop when you’re ready, and the other worktrees keep running independently.

---

Common Worktree Pitfalls When Running Agents

Worktrees are powerful but have a few gotchas, especially when agents are involved:

1. Locked branches: Git prevents you from checking out the same branch in two worktrees simultaneously. If feature/auth is checked out in ~/myapp-auth, you can’t check it out in another worktree. This is a safety feature. If you need two agents on the same logical task, create a second branch (feature/auth-v2) or use a single worktree with one agent.

2. Shared .git state: all worktrees share the same .git folder, so a git fetch or git gc in one worktree affects all of them. If an agent triggers a fetch or rebase, other agents might see new commits or refs. This is usually fine, but be aware that worktrees aren’t completely isolated—they share the repository’s internal state.

3. Submodules and worktrees: if your repository uses submodules, each worktree needs its own submodule checkouts. Git handles this automatically in recent versions, but older setups might require manual git submodule update in each worktree. If an agent depends on submodules, verify they’re initialized in the worktree before starting the session.

4. Disk space: each worktree is a full working directory. If your repository is large (e.g., a monorepo with gigabytes of files), multiple worktrees consume significant disk space. The .git folder is shared, so you’re not duplicating the entire history, but you are duplicating the working tree. Plan accordingly.

5. Forgetting to remove worktrees: after an agent finishes, you might forget to git worktree remove the directory. Orphaned worktrees clutter your filesystem and can confuse future git worktree list output. Clean up regularly.

6. Agent confusion with relative paths: if an agent or tool uses relative paths (e.g., ../config), it might behave differently in a worktree located outside the main repository directory. Most agents handle this fine, but double-check paths if you see unexpected behavior.

Best practice: treat each worktree as a temporary workspace for one agent session. Create it, run the agent, merge the work, and remove it. Don’t let worktrees accumulate indefinitely.

---

Mobile Oversight: Checking Agent Progress Across Worktrees from Your Phone

Running multiple agents in parallel is only useful if you can monitor and approve them without being chained to your desktop. This is where mobile oversight becomes essential.

The scenario: you’re away from your computer. You have three agents running:

• myapp-feature: Claude working on a new API endpoint, waiting for approval on a database schema change.
• myapp-hotfix: Codex fixing a null pointer bug, still running.
• myapp-experiment: another Claude session trying a refactor, auto-approved, no intervention needed.

You pull out your phone. You see:

• myapp-feature is blocked, needs approval. You review the schema diff, approve, and the agent continues.
• myapp-hotfix is progressing. You check the recent output, see it’s on track, and leave it alone.
• myapp-experiment is done. You see the final diff, decide it’s safe to merge, and make a note to merge it later from your desktop.

How this works with MobileVibe: each worktree is a folder on your desktop. Each agent session in that folder is a conversation. MobileVibe’s Desktop Connector exposes those conversations through a private tunnel. Your phone reaches your desktop, sees the active sessions, and lets you approve, monitor, or email-continue them. The agent history and files stay on your own computer; MobileVibe just makes them reachable from your phone.

Notifications: when an agent in a worktree needs approval or hits a limit, you get a push or email notification. You can respond immediately (approve from your phone) or defer (check it later when you’re at a real screen). The key is that you’re not blocked—agents can keep running in parallel, and you can unblock them from anywhere.

Email loop for worktrees: if you want to start a new agent in a specific worktree, you can email the project (the worktree folder). MobileVibe starts the agent there, tied to that branch. If you want to continue an existing conversation, you email that conversation. This works across all your worktrees—each is a separate project/folder, each can have its own agent sessions.

Practical tip: name your worktrees clearly (myapp-feature, myapp-hotfix) so you can identify them in the mobile UI. If you have five worktrees named temp1, temp2, etc., you’ll waste time figuring out which is which.

---

Scaling to Many Lanes: When Worktrees Become Your Development Backbone

For developers who fully embrace agent-driven development, worktrees stop being a nice-to-have and become the backbone of your workflow. Instead of one branch at a time, you run four, five, or ten agents in parallel, each in its own worktree, each making progress on a separate task.

Real-world scaling example:

• main worktree: stays clean, always on main, used for merging and releases.
• feature/auth worktree: Claude working on OAuth integration.
• feature/billing worktree: Codex implementing Stripe webhooks.
• fix/perf worktree: another Claude session optimizing a slow query.
• experiment/new-arch worktree: a speculative refactor, auto-approved, low priority.
• docs/api worktree: an agent updating API documentation based on recent code changes.

You check your phone during the day. You see:

• feature/auth needs approval (OAuth scopes). You approve.
• feature/billing hit a quota. You bump it.
• fix/perf is done. You merge it from your desktop later.
• experiment/new-arch is still running. You ignore it.
• docs/api is blocked on a missing endpoint. You reply via email with the endpoint details, and the agent continues.

This is the git worktree workflow at scale. You’re not typing code—you’re directing agents, approving changes, and merging finished work. Worktrees let you run many agents in parallel. Mobile oversight lets you manage them from anywhere. The result is a development process that’s faster, more parallel, and less dependent on being physically at your desk.

When to scale back: if you find yourself overwhelmed by too many lanes, reduce the number of active worktrees. Start with two or three, and add more as you get comfortable. The goal is to maximize throughput without losing track of what’s happening.

Storage and performance: running ten worktrees means ten working directories. If your repository is large, this can consume significant disk space. Monitor your disk usage and clean up finished worktrees promptly. The .git folder is shared, so you’re not duplicating the entire history, but you are duplicating the working tree.

Tooling: consider scripting common worktree operations. For example, a script to create a worktree, start an agent, and notify you when it’s done. Or a script to list all active worktrees and their agent statuses. These small automations make scaling to many lanes more manageable.

---

FAQ

What is a git worktree, and how does it differ from a traditional working tree?

A git worktree is an additional working directory linked to the same .git repository. A traditional working tree is the single directory where you check out branches and edit files. With worktrees, you can have multiple working directories (each with a different branch checked out) all sharing the same .git folder. This lets you work on multiple branches simultaneously without cloning the repository multiple times or switching branches in a single directory.

Can I run multiple AI agents simultaneously in separate git worktrees?

Yes. Each worktree is an independent directory with its own checked-out branch. You can start an agent (Claude, Codex, etc.) in each worktree, and they’ll work in parallel without interfering with each other. This is one of the primary benefits of using worktrees for agent-driven development—true parallelism without branch-switching or conflicts.

What happens if two agents try to modify the same files in different worktrees?

They won’t collide on disk because each worktree is a separate directory. However, when you merge their branches, you may encounter merge conflicts if they modified overlapping lines in the same files. Git will prompt you to resolve conflicts during the merge. The worktree setup prevents runtime collisions but doesn’t eliminate logical conflicts between branches.

How do I safely merge work from an agent-driven worktree back to main?

Review the agent’s final commits and diffs, then merge the branch as you normally would: git merge <branch> from your main worktree, or push the branch and open a pull request. After merging, you can remove the worktree with git worktree remove <path>. The branch and commits remain in the repository; only the working directory is deleted.

Can I monitor and approve agent progress across worktrees from my phone?

Yes, with MobileVibe. Each worktree is a folder on your desktop, and each agent session in that folder is a conversation. MobileVibe’s Desktop Connector exposes those conversations through a private tunnel, so you can check agent progress, approve changes, and unblock sessions from your phone. The agent history and files stay on your own computer; MobileVibe just makes them reachable from anywhere.

What are the performance or storage trade-offs of running many worktrees?

Each worktree is a full working directory, so if your repository is large, multiple worktrees consume significant disk space. The .git folder is shared, so you’re not duplicating the commit history, but you are duplicating the working tree. Performance is generally fine—worktrees don’t slow down git operations—but disk usage can add up. Monitor your disk space and clean up finished worktrees promptly.

How do I clean up or remove a worktree after an agent finishes its task?

Use git worktree remove <path>. For example, git worktree remove ../myapp-feature. This deletes the working directory but leaves the branch and commits in the repository. If you also want to delete the branch, use git branch -d <branch> after removing the worktree. Always verify the worktree is no longer needed before removing it.

Should I use worktrees for feature branches, bug fixes, or both?

Both. Worktrees are useful whenever you want to work on multiple branches in parallel. Feature branches, bug fixes, experiments, documentation updates—any task that benefits from isolation and parallelism is a good candidate. The key is whether you want to run multiple agents or tasks simultaneously without branch-switching. If yes, use worktrees.

---

Running git worktree agents in parallel transforms how you build software. Instead of one task at a time, you direct multiple agents across separate branches, approving and merging their work as it finishes. Worktrees provide the isolation; mobile oversight provides the flexibility. If you’re ready to scale your agent-driven workflow and manage multiple lanes from your phone, try MobileVibe free at mobilevibe.com and see how conversation-first development works across all your worktrees.