Running Claude Code Agents in Parallel

Running Claude Code parallel agents is easy for about twenty minutes. You open four terminal tabs, start four sessions, and feel productive. Then two of them edit the same file, a third has been sitting on a permission prompt for nine minutes while you weren't looking, and you can't remember which tab was doing the migration. The bottleneck stops being the model and becomes you, reading terminals.

Two things fix that. Isolation, so agents can't collide, and status, so you know which session wants something from you without visiting it. A macOS app called diri that appeared on August 4, 2026 does both, and it went from nothing to 205 stars in two days, with v0.4.1 shipping the day after launch.

Key Takeaways:

• Git worktrees are the isolation primitive. One checkout per agent, one branch each, one repo on disk.
• diri reads what an agent painted on screen to classify sessions as working, needs-you, or done. That detection is first-class for Claude Code and Codex, partial for Cursor and Gemini.
• A background Swift daemon owns the PTYs, so quitting the app doesn't kill sessions and a daemon restart brings conversations back.
• An MCP server lets a running agent spawn another agent, watch it, read its output, and answer its prompts.
• macOS 15 or newer, Apache-2.0, and Linux and Windows are not supported. A Rust port of the engine exists in the repo but hasn't shipped.

Why watching parallel agents is the hard part

Nobody struggles to start several agents. The trouble is the polling loop that lands on you afterwards.

A coding agent spends most of its wall-clock time in one of three states, and only one of them needs you. It's either working, in which case leave it alone; blocked on a question or a permission prompt, in which case every second you don't answer is dead time; or finished, in which case its work is sitting there unreviewed. Terminals don't distinguish between these. A tab that's thinking and a tab that asked you a question four minutes ago look identical until you click in.

Scale that to eight sessions and the cost isn't cognitive load, it's latency. Agents wait on you far more than you wait on them, which is the same reason humans and agents working in parallel breaks down long before the model does.

Git worktrees, the isolation that makes this safe

Before any orchestration tooling, the primitive worth learning is git worktree. One repository, several working directories, each on its own branch:

git worktree add ../feature-auth -b feature-auth
git worktree add ../fix-flaky-tests -b fix-flaky-tests

Each agent gets its own directory and its own branch, sharing one .git so you're not cloning the repo four times. They can't overwrite each other's files because they don't share files. Merge conflicts move to where they belong, which is merge time, instead of showing up as an agent mysteriously reverting a change you watched it make.

Two habits make this survivable at scale. Name the worktree after the branch so git worktree list reads like your task list, and prune aggressively; a stale worktree whose directory you deleted by hand leaves an entry behind until git worktree prune clears it, and the confusing failure that follows is worth avoiding.

git worktree list
git worktree remove ../feature-auth
git worktree prune

One caveat that bites people running claude code parallel agents for the first time: worktrees share the repository, not your untracked setup. Anything outside git, .env files, node_modules, local database fixtures, doesn't come along. Either your setup script runs per worktree or your agent's first act is discovering that nothing is installed.

This is the technique behind most serious parallel-agent setups, and you can run it with nothing but a shell. What you don't get from the shell is any idea of what those four agents are currently doing.

diri: a native macOS orchestrator for exactly this

cristicretu/diri runs Claude Code, Codex, Cursor, Gemini and plain shells in parallel, grouped by project, split across git worktrees or pushed out to a remote host over ssh and tmux. Each session is a real terminal with a real PTY, not a wrapper that reinterprets output.

It's not an editor and it isn't trying to be. There's no code pane and no Cursor-style inline diff. The window is a sidebar, terminal renderer, command palette and usage accounting, and the job it takes on is knowing which of your ten sessions deserves attention.

Install is a cask:

brew install --cask cristicretu/diri/diri

The full tap name is mandatory. A bare diri resolves only against Homebrew's default taps, and the cask lives in cristicretu/homebrew-diri rather than homebrew-cask, which the README explains as a notability threshold diri doesn't meet yet. That's a refreshingly blunt thing to put in your own install docs. The DMG from Releases is the same universal build, signed and notarised, and the app updates itself afterwards.

macOS 15 or newer. That's a hard requirement.

How the status detection works, and where it stops

The mechanism is screen scraping done deliberately. A headless terminal emulator inside the daemon renders what the agent actually painted, and per-agent rules decide whether that screen means working, waiting on you, or done.

Support is tiered, and the tiers matter more than the feature list suggests. Claude Code and Codex get first-class status detection and resume, which is unsurprising given both expose enough structure in their terminal workflows to classify against. Cursor and Gemini run with partial support. Anything else runs as a terminal with running or exited status, which is to say almost no signal at all.

Adding an agent is data rather than code: one JSON manifest under Sources/DirijorCore/Resources/manifests/ describing how to spawn it, how to resume it, which keys approve or deny a prompt, and the screen rules for classifying state. Copy the nearest existing manifest and edit it, no Swift or Rust involved. The contributing guide calls new manifests the easiest way to help, which is a sensible way to let the supported-agent list grow faster than the maintainer.

Sessions that outlive the window

Two processes, one wire protocol. The desktop app is Rust on GPUI, the UI framework from Zed. The daemon, dirijord, is headless Swift; the app launches it and it outlives the app. The daemon owns the PTYs and child processes, an offset-addressed output log per session so you can detach and replay, the headless emulator doing status detection, the session registry, worktrees and the control socket.

There's a third piece, dirijord-holder, whose only job is holding the PTY master so sessions survive a restart of the daemon itself. Quit diri, reopen it, and your conversations are still there. tmux users will recognise the shape of this immediately.

Persistence isn't a convenience feature here, it's what makes the whole arrangement usable. Claude code parallel agents that die when you close a laptop lid aren't parallel agents, they're a demo. The offset-addressed log per session is the piece doing the work: because output is addressed by byte offset rather than streamed and forgotten, the app can detach, reconnect later, and replay exactly what it missed instead of showing you a blank pane.

Remote hosts follow the same model over ssh and tmux, so a session can live on a VPS while the window stays on your Mac. NODE.md covers that setup. It's also the point where the local-versus-hosted question stops being philosophical, since you're now paying for a machine either way.

Building from source needs both toolchains, Rust pinned in diri/rust-toolchain.toml plus Swift 6 and the Xcode command-line tools, and the first Rust build compiles GPUI from a pinned Zed revision, which takes a while. Most people should take the cask.

A Rust port of the engine is underway in diri/crates/diri-engine with Linux and Windows as the goal. It has not shipped; the released app runs the Swift daemon, and PORT.md tracks what's left. Anyone who read "cross-platform soon" somewhere should check that file before planning around it.

Agents that spawn agents

The feature most likely to change how people use this is the MCP server. A running agent can spawn another agent, watch it, read its output and answer its prompts.

So the fan-out stops being something you do by hand. A lead session decomposes the work, starts a session per piece, and reads their status the same way you would; it's agent orchestration with a desktop app as the substrate instead of a framework. Whether that's a good idea depends heavily on the task, and it makes the status classification more important rather than less, because now an agent is the one deciding that a peer is stuck.

Parallel on your Mac versus parallel in the cloud

Running agents in parallel locally costs you a laptop. Ten PTYs, ten agent processes, ten checkouts, all competing with your editor for CPU, and every session dies when you close the lid or the battery goes. The worktrees survive; the running work doesn't.

The hosted version changes what the word parallel means. Each agent gets its own always-on machine instead of a slice of yours, so ten sessions is ten machines rather than ten processes fighting your editor for CPU, and none of them care whether the lid is open.

Keep the local setup for tight edit-run-review loops on code you are actively reading; nothing beats it on latency. But the moment a task is measured in hours rather than minutes, the laptop stops being an optimisation and becomes the constraint, which is the case for giving each agent its own always-on machine instead of a share of yours.

FAQ

Is diri free?

Yes. It's Apache-2.0 open source, installable via Homebrew cask or a DMG, with no paid tier advertised in the repository. The app does carry a usage accounting surface, though the README doesn't spell out what it meters; nothing in the repo suggests it gates anything behind payment.

Does diri work on Windows or Linux?

No. It requires macOS 15 or newer and ships as a universal build for Apple silicon and Intel. A Rust port of the engine aimed at Linux and Windows is in progress in the repo, but the released app still runs the Swift daemon, so treat cross-platform support as unshipped.

Which coding agents get full support?

Claude Code and Codex have first-class status detection and resume. Cursor and Gemini are partial. Anything else runs as a plain terminal with running or exited status. Adding proper support for another agent means writing one JSON manifest, not patching the app.

Do I need git worktrees to run agents in parallel?

Not strictly, but you want them. Without isolation, two agents editing the same checkout will overwrite each other's work in ways that are tedious to untangle. A worktree per agent gives each one its own directory and branch off a single repo, and diri can create and manage them for you.