Running Multiple AI Coding Agents in Parallel with Git Worktrees

Quick answer

Git worktrees let you check out multiple branches from the same repository into separate folders, each with its own working directory. When you pair worktrees with folder-scoped AI coding agents, you can run parallel agent sessions—one per worktree—without conflicts, then merge completed work back to main. MobileVibe makes this practical from mobile by treating each worktree as a distinct conversation you can monitor, approve, and resume from your phone.

Key takeaways

• Parallel agent lanes beat sequential handoffs: multiple agents work on separate features simultaneously, each in its own worktree folder.
• Git worktrees share the same .git database but provide isolated working directories, so agents never collide on files.
• Folder-scoped conversations in MobileVibe map one agent session to one worktree, making it clear which lane needs attention.
• Mobile monitoring shows which agents are blocked, which are still working, and which worktrees are safe to merge—all from your phone.
• Auto-approve rules (where supported) let trusted agents continue while you’re away; notifications alert you when manual input is required.
• Merge patterns vary: rebase for linear history, squash for clean commits, or standard merge when you need full branch context.

---

Why Parallel Agent Lanes Beat Sequential Handoffs

When you direct AI coding agents to build features, refactor modules, or fix bugs, the default pattern is sequential: start an agent, wait for it to finish or block, review, then start the next task. This works for small changes, but it wastes time when tasks are independent. A backend API endpoint and a frontend component can be built in parallel if they don’t share files.

Parallel agent lanes mean running multiple agents at the same time, each working in its own isolated folder. You might have:

• Lane 1 (worktree feature/api-auth): Codex building a new authentication endpoint.
• Lane 2 (worktree feature/ui-dashboard): Claude refactoring the dashboard UI.
• Lane 3 (worktree fix/rate-limit): Cursor fixing a rate-limit bug in a shared utility.

Each agent sees only its own worktree’s files. They can’t step on each other’s changes, and you can review or merge each lane independently. From your phone, you see three conversations in your MobileVibe dashboard: one per worktree. When feature/api-auth needs approval, you handle it without interrupting the other two.

Sequential handoffs force you to babysit one agent at a time. Parallel lanes let you start multiple agents, go do something else, and return (from mobile or desktop) to triage what needs attention. The agents that can proceed do; the ones that need input wait in your inbox.

---

Setting Up Git Worktrees for Multi-Agent Workflows

Git worktrees are a built-in Git feature that lets you check out multiple branches into separate directories, all sharing the same .git repository. This is lighter than cloning the repo multiple times and keeps all branches in sync with one shared database.

Creating a worktree

From your main repository folder (e.g., ~/projects/myapp), create a new worktree for a feature branch:

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

This checks out the feature/api-auth branch into a sibling folder ../myapp-feature-api. The new folder has its own working directory and HEAD, but shares .git with the main repo. You can create as many worktrees as you need:

git worktree add ../myapp-ui-dashboard feature/ui-dashboard
git worktree add ../myapp-fix-rate-limit fix/rate-limit

Now you have three folders, each representing a different branch. List active worktrees with:

git worktree list

Folder structure

Your filesystem looks like:

~/projects/
  myapp/               # main worktree (e.g., main branch)
  myapp-feature-api/   # worktree for feature/api-auth
  myapp-ui-dashboard/  # worktree for feature/ui-dashboard
  myapp-fix-rate-limit/# worktree for fix/rate-limit

Each folder is a valid Git working directory. You can cd into any of them, run tests, start an agent, or open an IDE. Because they share the same .git, commits in one worktree are immediately visible to the others (after a git fetch or git pull in the main repo).

Cleaning up

When a feature is merged and you no longer need the worktree:

git worktree remove ../myapp-feature-api

This removes the folder and unregisters the worktree. The branch itself remains in the repository; you can delete it separately if needed.

---

Assigning Agents to Isolated Worktrees: Folder-Scoped Conversations

MobileVibe conversations are folder-scoped: each conversation is tied to a specific folder on your desktop. When you start an agent in a worktree folder, MobileVibe creates a conversation for that folder and agent. The agent sees only the files in that worktree, and the conversation history stays associated with that folder.

Starting agents in worktrees

Open a terminal or IDE in the worktree folder and start the agent. For example, in ~/projects/myapp-feature-api:

cd ~/projects/myapp-feature-api
codex "Add JWT authentication to the /login endpoint"

Or open Claude Desktop, set the project folder to ~/projects/myapp-feature-api, and start a chat. MobileVibe’s Desktop Connector sees the agent session and folder path, and creates a conversation entry. On your phone, you’ll see a conversation labeled with the folder name and agent.

Repeat for other worktrees:

cd ~/projects/myapp-ui-dashboard
claude "Refactor the dashboard to use the new API endpoints"

Now you have two parallel agent sessions, each isolated to its own worktree. The agents can’t conflict because they’re working on different branches in different folders.

Folder naming and labels

Use descriptive worktree folder names that match the branch or task. This makes it easy to identify conversations on mobile. MobileVibe shows the folder path in the conversation list, so myapp-feature-api and myapp-ui-dashboard are immediately distinguishable.

Agent and surface combinations

You can mix agents and surfaces across worktrees. One worktree might use Codex CLI, another Claude Desktop, another Cursor. Each conversation is independent. MobileVibe tracks the agent and surface per conversation, so when you resume from your phone, it knows whether to open Claude Desktop, run a Codex command, or (where supported) drive Cursor.

---

Monitoring and Approving Work Across Multiple Lanes from Mobile

With parallel agent lanes running, your MobileVibe dashboard becomes an inbox of what needs attention. Each conversation shows its status: working, blocked, needs approval, or completed. You can see at a glance which worktrees are progressing and which need input.

Dashboard view

Open the MobileVibe app on your phone. The conversation list shows:

• myapp-feature-api (Codex): “Needs approval” — Codex wants to install a new dependency.
• myapp-ui-dashboard (Claude): “Working” — Claude is refactoring components.
• myapp-fix-rate-limit (Cursor): “Needs input” — Cursor hit an API quota and paused.

Tap a conversation to see the latest messages, diffs, and agent output. If an agent needs approval, you can approve or reject the proposed change directly from your phone. The agent resumes on your desktop, and you move to the next conversation.

Notifications

MobileVibe can send push or email notifications when an agent changes state. For example, when myapp-feature-api moves from “working” to “needs approval,” you get a notification. You can configure notifications per conversation or globally, so you’re alerted only for high-priority lanes.

Email notifications include a link to continue the conversation. Replying to the email sends your message to the agent, which resumes work. This is useful when you’re away from the app but want to unblock an agent quickly.

Resuming from mobile

When you open a conversation on your phone, MobileVibe connects to your desktop through the Desktop Connector’s private tunnel. You see the agent’s current state and can send new instructions. The agent runs on your real machine, so it has access to the worktree’s files, terminal, and tools. You’re not SSH-ing or streaming a desktop—you’re driving the agent remotely.

If the agent is Claude or Codex, MobileVibe can resume the session in the same surface (CLI or IDE) where it started. For Cursor or Windsurf, resuming depends on the host app’s support; MobileVibe may open the conversation in a supported surface or show you the history to continue manually.

---

Syncing Changes Back to Main: Merge Patterns and Conflict Resolution

Once an agent finishes work in a worktree, you need to merge the changes back to the main branch. Git worktrees make this straightforward because they share the same .git database.

Merge patterns

Rebase for linear history: If you want a clean, linear commit history, rebase the worktree branch onto main before merging:

cd ~/projects/myapp-feature-api
git fetch origin
git rebase origin/main
git push --force-with-lease

Then merge into main (from the main worktree or GitHub/GitLab):

cd ~/projects/myapp
git checkout main
git merge feature/api-auth --ff-only

Squash for clean commits: If the agent made many small commits, squash them into one:

cd ~/projects/myapp
git checkout main
git merge feature/api-auth --squash
git commit -m "Add JWT authentication to /login endpoint"

Standard merge: If you need the full branch history (e.g., for audit or collaboration), use a standard merge:

git merge feature/api-auth --no-ff

Conflict resolution

If two worktrees modified overlapping code, you’ll see merge conflicts when you try to merge. This is rare if you assigned agents to independent features, but it happens when shared utilities or config files are touched.

Resolve conflicts in the main worktree or in the feature worktree before merging. Open the conflicted files, choose the correct changes, and commit. If an agent was involved, you can ask it to help resolve the conflict by showing it the diff and the conflict markers.

Keeping worktrees in sync

Periodically pull changes from main into each worktree to avoid large divergences:

cd ~/projects/myapp-feature-api
git fetch origin
git merge origin/main

This keeps the worktree up to date with other merged features. If an agent is actively working, wait until it’s idle to avoid disrupting its context.

---

Auto-Approve Rules and Notification Strategies for Parallel Runs

When running parallel ai coding agents worktree sessions, you don’t want to babysit every approval request. Auto-approve rules (where supported by the agent or MobileVibe) let trusted agents continue without manual intervention. Notification strategies ensure you’re alerted only when necessary.

Auto-approve rules

Some agents and surfaces support auto-approve for specific actions. For example, you might auto-approve:

• Installing dependencies from a known package manager (npm, pip).
• Running tests or linters.
• Creating new files in a designated folder.

Configure auto-approve rules in the agent’s settings or in MobileVibe’s conversation preferences. When an agent proposes an action that matches a rule, it proceeds automatically. You see the action in the conversation history but aren’t interrupted.

Use auto-approve cautiously. Don’t auto-approve actions that modify production config, delete files, or run shell commands you haven’t reviewed. For parallel lanes working on isolated features, auto-approve is safe for routine tasks like dependency updates or test runs.

Notification strategies

Configure notifications to match your workflow:

• High-priority lanes: Enable push notifications for conversations where you need immediate feedback (e.g., a production hotfix).
• Low-priority lanes: Use email notifications or check the dashboard periodically.
• Batch notifications: Group notifications by time (e.g., every 30 minutes) to avoid constant interruptions.

MobileVibe’s notification settings let you choose per conversation or globally. For parallel runs, you might enable push for one critical worktree and email for the others.

Handling blocked agents

When an agent is blocked (needs approval, hit a quota, or encountered an error), it stays in the “blocked” state until you intervene. From your phone, you can:

• Approve or reject the proposed change.
• Send a clarifying message to help the agent proceed.
• Mark the conversation as “review later” and move to the next lane.

The goal is to triage quickly: unblock what you can, defer what needs desktop review, and let the rest continue.

---

Common Pitfalls: State Drift, Credential Scope, and Agent Confusion

Running multiple agents in parallel worktrees is powerful, but it introduces complexity. Here are common pitfalls and how to avoid them.

State drift

Problem: Worktrees diverge from main over time. An agent in one worktree assumes a file structure or API that was changed in another worktree’s merged feature.

Solution: Regularly merge main into active worktrees. Before starting a new agent session, pull the latest changes. This keeps worktrees synchronized and reduces merge conflicts.

Credential scope

Problem: Some agents or tools cache credentials per folder. If you start an agent in a worktree and it authenticates to an API, the credentials might not be available in another worktree.

Solution: Use global credential stores (e.g., ~/.config, environment variables, or OS keychains) rather than per-folder config files. Ensure API keys and tokens are accessible to all worktrees. Do NOT send credentials through email or store them in conversation history.

Agent confusion

Problem: An agent in one worktree references files or state from another worktree, causing errors or incorrect assumptions.

Solution: Clearly scope each agent’s task to its worktree. When starting an agent, specify the folder and branch context. Avoid vague instructions like “update the API” if multiple worktrees are working on different parts of the API. Be explicit: “In this worktree (feature/api-auth), add JWT validation to the /login endpoint.”

Overlapping file edits

Problem: Two agents modify the same file in different worktrees, leading to merge conflicts.

Solution: Assign agents to non-overlapping features. If overlap is unavoidable, merge one worktree first, then rebase the other onto the updated main. Review conflicts carefully—don’t blindly accept one side.

Notification overload

Problem: With many parallel lanes, you get too many notifications and miss critical ones.

Solution: Use notification filters and priorities. Enable push for high-priority lanes, email for others. Batch notifications or set quiet hours. Review the dashboard periodically to catch anything that slipped through.

Forgetting to remove worktrees

Problem: Old worktrees accumulate on disk, consuming space and cluttering the workspace.

Solution: After merging a feature, remove the worktree with git worktree remove. Periodically run git worktree list to audit active worktrees and clean up stale ones.

---

FAQ

Can I run Claude, Codex, and Cursor agents on different worktrees at the same time?

Yes. Each worktree is a separate folder, and each agent session is scoped to its folder. You can start Claude Desktop in one worktree, Codex CLI in another, and Cursor in a third. MobileVibe tracks each conversation independently, so you can monitor and resume all three from your phone. The agents won’t interfere with each other because they’re working on different branches in isolated directories.

How does MobileVibe know which agent to resume when I open a conversation from my phone?

MobileVibe stores the agent type and surface (CLI or IDE) for each conversation. When you open a conversation on your phone, it connects to your desktop and attempts to resume the session in the same surface where it started. For Claude and Codex, this is usually straightforward because they share a native store or CLI. For Cursor or Windsurf, resuming depends on the host app’s support; MobileVibe may open the conversation in a supported surface or show you the history to continue manually.

What happens if two agents try to edit the same file in different worktrees?

They can’t—each worktree has its own working directory. If two agents are assigned to different worktrees, they’re editing separate copies of the file (one per branch). When you merge the branches back to main, Git will detect the conflicting changes and prompt you to resolve them. This is the same as any multi-branch workflow. To avoid conflicts, assign agents to non-overlapping features or merge one branch first, then rebase the other.

Can I set up auto-approve rules so agents don’t block while I’m away?

Where supported by the agent or MobileVibe, yes. Auto-approve rules let you specify actions that can proceed without manual approval (e.g., installing dependencies, running tests). Configure these rules in the agent’s settings or in MobileVibe’s conversation preferences. Use auto-approve cautiously—don’t auto-approve actions that modify production config or run untrusted shell commands. For parallel lanes working on isolated features, auto-approve is safe for routine tasks.

How do I safely merge worktree changes back to main without losing agent context?

Merge the worktree branch into main using your preferred Git workflow (rebase, squash, or standard merge). The agent’s conversation history stays in MobileVibe, tied to the worktree folder. After merging, you can archive or remove the worktree. If you need to continue the conversation, you can resume it in the main worktree or a new worktree for the next task. MobileVibe doesn’t lose context when you merge—it’s just a Git operation.

Do I need separate API keys or credentials for each agent lane?

No. Agents running in different worktrees can share the same API keys and credentials, as long as those credentials are stored globally (e.g., in environment variables or OS keychains). Some agents cache credentials per folder, so check your agent’s documentation. If you’re running multiple agents in parallel, ensure your API provider’s rate limits and quotas can handle the combined load.

Can MobileVibe send me a notification when an agent in a specific worktree needs input?

Yes. MobileVibe can send push or email notifications when a conversation changes state (e.g., from “working” to “needs approval”). You can configure notifications per conversation, so you’re alerted only for specific worktrees. For example, enable push notifications for a high-priority feature worktree and email for others. Notifications include a link to open the conversation on your phone or reply via email.

What’s the difference between a worktree strategy and just opening multiple IDE windows?

Opening multiple IDE windows in the same folder (or different folders that are clones of the same repo) can lead to file conflicts and confusion. Git worktrees provide isolated working directories for each branch, so agents never collide on files. Worktrees also share the same .git database, so commits and branches are immediately visible across all worktrees. This is lighter and cleaner than cloning the repo multiple times. With MobileVibe, each worktree becomes a distinct conversation you can monitor and resume from mobile, making parallel agent lanes practical.

---

Running parallel ai coding agents worktree sessions transforms how you build with AI. Instead of babysitting one agent at a time, you start multiple lanes, let them work, and triage from your phone when they need input. Git worktrees provide the isolation, MobileVibe provides the mobile control, and you get more done in less time. Try MobileVibe free and see how parallel agent lanes fit your workflow—start a few worktrees, kick off agents, and check progress from anywhere.