{"slug": "parallel-coding-agents-without-repository-collisions", "title": "Parallel Coding Agents Without Repository Collisions", "summary": "A developer outlined a workflow for running parallel coding agents without repository collisions, combining one Git worktree and branch per agent with atomic task claims, branch locks, file-ownership plans, and an ordered merge queue. The approach isolates filesystem and service-level conflicts by giving each workspace its own port range, test database, cache path, and generated-output folder, while reserving shared-contract changes for the first merge. The writeup also recommends heartbeat-based claim expiry, per-task limits on time, retries, tool calls, and cost, and reviewing uncommitted work before automatic worktree cleanup.", "body_md": "Three coding agents can finish three tasks at once. They can also overwrite the same file, reuse one port, or merge against old code. Speed only helps when each agent has a clear place to work and a safe path back to the main branch.\n\nThe goal is not “more agents.” The goal is useful work that can merge with less waiting and less repair.\n\nA branch is not enough when several processes use the same folder. One agent may change files while another is testing them. Build output, lock files, caches, and local databases can also collide.\n\nUse one Git worktree per coding agent. A worktree gives each agent its own folder and branch while sharing the same Git history.\n\n```\n# Create three isolated workspaces from the current repository\ngit worktree add ../repo-api -b agent/api\ngit worktree add ../repo-ui -b agent/ui\ngit worktree add ../repo-tests -b agent/tests\n\n# Check every active workspace before starting agents\ngit worktree list\n```\n\nThe VibeFlow CLI can create this shape with `vibeflow launch --worktree --new-branch --provider codex`. Its [official README](https://github.com/axiom-studio/vibeflow-cli/blob/main/README.md) also provides commands to list sessions, inspect worktrees, and check for conflicts.\n\nIsolation stops folder collisions. It does not stop two agents from solving the same ticket or editing the same shared file.\n\nUse an atomic task claim. The first agent that claims a work item owns it until completion, release, or timeout. Record the session, branch, working directory, commit, and last heartbeat.\n\nVibeFlow agent sessions follow this pattern: initialize, poll, claim, execute, commit, and complete. Code-changing personas also use one live session per branch. A second session gets a `branch_locked` result instead of racing the first one.\n\n| Control | What it prevents | Evidence to keep | \n|---|---|---|\n| Worktree per agent | Files changing under another process | Worktree path and branch | \n| Atomic task claim | Duplicate work | Work item and session ID | \n| Branch lock | Two writers on one branch | Lock owner and heartbeat | \n| File ownership note | Shared-file surprises | Planned file list | \n| Ordered merge queue | Stale merges | Tested commit and merge order | \n\nAsk each agent to list the files it expects to change. Reject or split plans that overlap on high-risk files such as dependency locks, database migrations, generated clients, root configuration, and shared types.\n\nA simple plan might be:\n\n`services/api/**`.` apps/web/**`.` tests/e2e/**`.` package-lock.json`, migrations, and shared schemas.\nFile ownership is a planning rule, not a security boundary. Agents still need tests and review.\n\nWorktrees can still collide through services outside Git. Give each workspace its own port range, cache path, temporary directory, database name, and generated-output folder.\n\n```\nexport AGENT_SLOT=2\nexport PORT=$((3000 + AGENT_SLOT))\nexport TEST_DB=\"app_test_${AGENT_SLOT}\"\nexport CACHE_DIR=\".cache/agent-${AGENT_SLOT}\"\nnpm test\n```\n\nDo not share a writable local database between agents. Do not let two agents regenerate the same checked-in file. If generation is required, assign it to the integrator after upstream branches merge.\n\nAgents should not all merge when they finish. Merge the branch that changes shared contracts first. Rebase or update the remaining branches, then rerun their checks.\n\nUse this order:\n\nThe commit that passed should be the commit that ships. If the merge creates a new commit, run the required checks again.\n\nA heartbeat shows that a process is alive. It does not prove useful progress. Set limits for task time, retry count, tool calls, and cost. Release a claim when the heartbeat expires. Let a human terminate a live but stuck session after checking its logs and uncommitted diff.\n\nBefore cleanup, save or review uncommitted work. Automatic worktree removal can delete changes that were never committed.\n\nStart with three tasks that touch different areas. Create three worktrees and branches. Claim each task. Review planned files. Run agents with separate ports and caches. Merge the shared contract first. Update the other branches. Run focused and full tests. Then release the exact tested artifact.\n\n[VibeFlow](https://docs.axiomstudio.ai/vibeflow) coordinates agent roles, work claims, security review, QA, and Git records. Its [agent-session controls](https://docs.axiomstudio.ai/vibeflow/agent-sessions) add branch locks and worktree-aware ownership. Teams can also use [Vera](https://axiomstudio.ai/solutions/ai-code-review) as an independent review step before merge.\n\nParallel work becomes reliable when ownership is visible. Give every agent one task, one workspace, one branch, and one merge path.", "url": "https://wpnews.pro/news/parallel-coding-agents-without-repository-collisions", "canonical_source": "https://dev.to/mahendra_navale_0cd194502/parallel-coding-agents-without-repository-collisions-gfm", "published_at": "2026-11-21 22:05:14+00:00", "updated_at": "2026-11-21 22:11:43.727030+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Git", "VibeFlow", "Codex", "axiom-studio"], "also_reported_by": [], "takeaway": "Giving each coding agent its own Git worktree and branch, plus an atomic task claim and branch lock, prevents duplicate work and files changing under another process, while separate port ranges, test databases, and cache paths stop collisions outside Git.", "recommendation": {"advice": "Run one Git worktree and branch per coding agent, enforce atomic task claims and branch locks, and merge shared-contract branches first before rebasing and re-running checks.", "playbook": "coding-agents", "playbook_url": "https://wpnews.pro/playbooks/coding-agents"}, "alternates": {"html": "https://wpnews.pro/news/parallel-coding-agents-without-repository-collisions", "markdown": "https://wpnews.pro/news/parallel-coding-agents-without-repository-collisions.md", "text": "https://wpnews.pro/news/parallel-coding-agents-without-repository-collisions.txt", "jsonld": "https://wpnews.pro/news/parallel-coding-agents-without-repository-collisions.jsonld"}}