Git Worktrees Solve the Parallel Agent Conflict Problem

·https://github.com/standardagents/dmux
repoaicliagent-loopstmuxgitterminalparallel-execution

worktree-per-agent isolation pattern directly relevant to joelclaw agent loop architecture — each story branch could run in its own worktree instead of serially

The core problem with running multiple Claude Code, Codex, or pi sessions against the same repo simultaneously is that they step on each other. Shared working directory, shared branch, racing writes. dmux from Standard Agents solves this at the OS level: one tmux pane, one git worktree, one branch, per agent. Each agent gets a complete isolated working copy of the repo. No conflicts.

The interaction model is minimal. Press n to create a new pane, type a prompt, pick which agents to launch (or just get a plain terminal), and dmux handles branch creation, worktree setup, and agent invocation. The list of supported agents is already comprehensive — Claude Code, Codex, OpenCode, Cline CLI, Gemini CLI, Qwen CLI, Amp, pi, Cursor CLI, Copilot CLI, and Crush. The multi-select launch is interesting — you can fire the same prompt at multiple agents in parallel and see what each one produces.

Merging is where it gets practical. When an agent finishes, you open the pane menu (m) and choose Merge — it auto-commits any uncommitted work, merges into the main branch, and cleans up the worktree. Branch names and commit messages are generated automatically via OpenRouter if you supply a key. The lifecycle hooks (worktree create, pre-merge, post-merge) give you escape hatches for running tests or linting before anything lands.

The relevance to the joelclaw agent loop system is direct. The current loop architecture runs stories serially — plan, test-write, implement, review, judge, repeat. Worktree-per-story parallel execution is the obvious next shape: branch each story, run implementors in parallel, merge winners. dmux is doing exactly this pattern, just at the tmux/CLI level rather than through an Inngest workflow. Worth tracking as a reference implementation of the isolation model.

Key Ideas

  • Worktree-per-agent is the key primitive — git worktrees give each agent a full working copy with zero coordination overhead between them
  • tmux as orchestration surface — panes map 1:1 to tasks/agents, visibility controls let you hide/isolate/restore without stopping work
  • Multi-agent fan-out — same prompt dispatched to multiple agents simultaneously, useful for cross-checking or competing implementations
  • AI branch naming via OpenRouter — removes the cognitive overhead of naming branches during fast iteration
  • Lifecycle hooks (worktree create, pre-merge, post-merge, and more) enable test-gate patterns before merging agent output
  • Multi-project sessions — multiple repos in the same dmux session, useful for cross-repo agent work
  • macOS native notifications for background panes — agent finishes and taps you on the shoulder
  • Built-in file browser (f) to inspect a worktree’s state without leaving the session
  • From formkit/dmux originally — the “dmux-on-dmux” development loop described in CONTRIBUTING.md is a nice dogfood story

Links

← All discoveries