How to Organize AI Coding Worktrees on macOS

How to organize AI coding worktrees on macOS

A working blueprint for parallel agents on macOS comes down to four moves: keep one canonical repo, give every session its own isolated git worktree on a unique branch, write down what each session is doing, and run a quick collision check before launching more than one agent. That structure is what keeps 3–10 simultaneous runs traceable instead of chaotic.

The core idea is that filesystem organization is the actual problem, not the agent. A git worktree puts a branch's content into its own directory while sharing the repository's .git database (Source: filiph.net). Each session gets isolated files and an isolated index, so two agents editing the same repo never trample each other.

Most worktree guides treat the pieces separately. This blueprint connects them:

1. A repeatable folder convention for repos, sessions, prompts, and artifacts.
2. A naming scheme that survives context switches between agents.
3. The exclusion rules you need when worktrees live inside the project.
4. A runtime checklist for ports, dependencies, and databases before agents start editing.

Cole Medin reports running 3–10 Claude Code agents in parallel on isolated worktrees (Cole Medin, "Parallel Claude Code + Git Worktrees," published 04/22/2026; the video runs 23 minutes 53 seconds). At that density, ad-hoc git worktree add invocations stop being enough — you need a layout you can rebuild from memory.

How do git worktrees work for AI coding agents?

A git worktree is a separate working directory linked to the same repository, with its own branch checkout, its own index, and its own files on disk, while sharing the one .git database of commits (Source: Nimbalyst). The command git worktree add ../feature-branch feature-branch gives you a second directory on a second branch without re-cloning.

The distinction from a git clone is what makes worktrees the isolation primitive for parallel agents. As Filip Hráček puts it, worktrees share the same .git (no database duplication), keep state synchronized so you don't have to git fetch in two places, and let rebase, merge, and cherry-pick work immediately because the branches still live in one repo (Source: filiph.net).

That matters because AI agents autonomously edit files for long stretches. Two agents in the same directory will corrupt each other's work; two agents in two worktrees won't (Source: Nimbalyst). Worktrees give each agent a place to run without racing the others on package.json, lockfiles, or in-progress edits between test runs.

How should I structure folders for parallel AI coding sessions on macOS?

The repeatable convention separates three things: long-lived repos, ephemeral per-session folders, and shared references. The mq-dir layout organizes ~/dev into _shared/ for prompts and references, sessions/ for per-run notes and artifacts, and repos/ for the canonical checkout — with sessions/*/repo/ being a git worktree rather than a clone, which saves disk and keeps refs unified (Source: mq-dir). That structure is presented as a system designed to survive 10 parallel sessions.

The session folder is where traceability lives. In the mq-dir workflow, every session directory includes a CLAUDE.md file recording the goal, out-of-scope items, and constraints, so a session can be resumed and corrected after you context-switch away and back (Source: mq-dir).

A minimal version on macOS looks like this:

The reason to keep ephemeral sessions out of the canonical repo is recovery: deleting a finished session leaves your real repo untouched, and the shared .git means nothing was duplicated.

Where should git worktrees live on disk for AI coding?

Three layouts dominate, and the right one depends on how much you mind a cluttered projects directory. You can nest worktrees inside the project, place them as siblings, or collect them in a separate sessions directory.

Filip Hráček nests worktrees inside the project (experimental/alice, experimental/bob) so his ~/dev directory isn't polluted by a pile of branch folders, but notes that other people put them as siblings instead (Source: filiph.net). The mq-dir approach is the third option: a dedicated sessions/ tree where each session's repo/ is a worktree (Source: mq-dir).

There's a macOS-specific wrinkle when a sandboxed user is involved. Mike McQuaid puts repositories and worktrees under /Users/Shared/sv-mike so both his normal user and a separate sandboxed user can read and write them (Source: mikemcquaid.com). If you're not sandboxing, a per-user path under ~/dev is simpler. The sources don't establish a recommended maximum number of concurrent worktrees for a typical Mac, so size it to your machine.

What branch and directory names keep agent worktrees traceable?

Each session needs a unique branch and a directory path that mirrors it. Git will not let you check out the same branch in two worktrees, so every session needs either a unique branch (session/...) or a detached HEAD — and most hand-rolled scripts get this wrong the first time (Source: Nimbalyst).

For readability, Filip Hráček names agents alice and bob rather than a/b (a single character is easy to miss) or Greek letters (overloaded with "alpha branch" meanings), and matches the directory path to the branch name so the layout reads cleanly (Source: filiph.net). He also keeps AI agents off main — that branch is for humans only — and creates dedicated branches like experimental/alice instead.

Practical rules that fall out of the corpus:

• Mint one unique branch per session; never check the same branch into two worktrees.
• Make the directory path match the branch name so a glance tells you which agent is which.
• Use names you can say out loud during a context switch ("Alice is still on the rename"), not llm_a or foo.

What has to be excluded when worktrees live inside the project?

Nested worktrees create duplicate files that Git, your editor, and static analysis will all try to scan unless you stop them. Filip Hráček's rule for in-project worktrees is direct: you need to ignore them in .gitignore, in static analysis, and in the IDE (Source: filiph.net). Skip any one of those and you'll get duplicate symbols, doubled lint results, or an editor indexing the same code three times.

The exclusions group into three:

• Git: add the worktree directory to .gitignore so the nested checkouts don't show up as untracked noise in your canonical repo.
• IDE and static analysis: exclude the worktree paths from indexing and from your analyzer's scan roots, or every duplicate file gets flagged.
• Shared-user Git safety: when worktree directories are owned by another user — like the sandboxed setup under /Users/Shared — Git refuses the paths until you add safe.directory entries in ~/.gitconfig (Source: mikemcquaid.com).

Sibling and dedicated-sessions layouts sidestep the Git and IDE exclusions entirely, which is part of why the corpus practitioners who nest worktrees treat the ignore rules as mandatory rather than optional.

How do you run 3-5 isolated agents simultaneously without chaos?

Worktrees isolate files, but they don't isolate the runtime — and that's where parallel agents actually collide. Cole Medin names the three problems that show up when you scale: port conflicts, dependency duplication, and the silent killer, database collisions when several agents run migrations at once (Source: YouTube, "Parallel Claude Code + Git Worktrees").

Run this check before launching the second, third, and fourth agent:

1. Ports: assign each session a distinct port (or port range) so two dev servers don't fight over the same one.
2. Dependencies: decide whether each worktree installs its own node_modules or shares a cache — duplication eats disk fast across five sessions.
3. Environment variables: give each session its own env so secrets and config don't leak across agents.
4. Service logs: route each session's logs somewhere you can read them. As one Hacker News commenter notes, containers make this easier because agents see service output directly; outside a container you have to send logs somewhere the agent can see (Source: Hacker News).
5. Database: never let multiple agents run migrations against one shared database. Cole Medin uses database branching (via Neon) to give each agent its own database instance (Source: YouTube).

The corpus doesn't provide a measured disk-usage figure for worktrees versus clones on macOS, so treat dependency duplication as something to monitor rather than a number to plan around.

How do I avoid conflicts when multiple AI agents edit the same repo?

The cleanest way to avoid merge pain is upstream of the merge: give each agent a non-overlapping task. Worktrees stop agents from corrupting each other's files in real time, but two agents editing the same module on different branches still produce conflicting diffs when you merge. The fix is task selection, not tooling.

Choose work that touches different files or layers — one agent on the API, another on the UI, a third on tests — so their branches rarely intersect. Cole Medin's workflow goes further, separating planning, implementing, and validating into distinct sessions, with fresh-context reviews catching bugs the implementer missed (Source: YouTube). That "factory mindset" keeps each branch reviewable on its own terms.

Keep changes small enough to review. The harder problem starts when several finished branches need to land. For a structured approach to that, see how to review five AI agent branches without merge chaos and the broader git workflow for parallel AI agents — both cover checking overlap first and merging in dependency order.

Worktrees vs separate clones for AI coding sessions

For most AI coding sessions, worktrees beat separate clones because they isolate working directories without duplicating the .git database or desynchronizing refs. A worktree shares the one object store, so commits, branches, and history stay consistent everywhere, and git fetch in one place updates all of them (Source: filiph.net).

Clone-like isolation still appeals in one case from the corpus: a Hacker News commenter wanted simple worktree management for an already-checked-out local repo specifically to avoid cloning from GitHub and reinstalling dependencies for every workspace (Source: Hacker News). That's the failure mode of clone-based tools — for a project with heavy dependencies, re-cloning means rebuilding the whole environment before you can test anything. Worktrees keep the shared history; you still handle dependencies per directory.

When should you add a workspace layer on top of Git worktrees?

Add a workspace layer once filesystem organization stops being enough to track what each agent is doing. Worktrees solve isolation on disk, but they don't tell you which of your 3–10 sessions is waiting for input, which errored, and which is still running. That visibility gap is where a session-aware macOS workspace helps — without replacing Git, your shell, or your agents.

The tells that you've outgrown plain worktrees: you're losing track of which pane needs a prompt, you're retyping the same command across sessions, and closing your terminal means rebuilding the whole layout. The corpus shows a whole category growing around this — Nimbalyst, Conductor, Vibe Kanban (10-plus CLI agents), and Superset (10-plus parallel agents) all add a UI over worktrees (Source: Nimbalyst). The Conductor Show HN thread alone drew 228 points and 115 comments (Source: Hacker News), signaling real demand for visible parallel sessions.

CodeGrid fits this gap as a native macOS workspace: each agent session runs in its own PTY-backed pane on a free-form 2D canvas, with live status indicators visible even zoomed out, and it restores your sessions, directories, and layout on restart so the worktree structure you built doesn't have to be rebuilt by hand.

If you're deciding whether the filesystem alone is enough, the practical guides on running 10+ AI coding agents in parallel and keeping idle vs running sessions triaged fast cover where visibility starts to matter.

You can download CodeGrid for macOS if you want to try that workspace layer on top of your existing worktrees.