Parallel Code: run Claude Code, Codex and Gemini in separate git worktrees

The problem Parallel Code targets: one agent, one working directory

A single checkout is a serial resource. If Claude Code is editing files in your repository, a second agent cannot work on a different feature at the same time without stepping on the same files, the same index, and the same branch. The usual workaround is to clone the repository several times, or to learn git worktree by hand and keep track of which directory holds which branch. Both work, and both are manual bookkeeping.

Parallel Code is aimed at engineers who already pay for or use one of the supported coding CLIs and want several of them running at once. The README frames the pitch as "Ten agents. Ten branches. One afternoon." and the comparison table in the README is explicit about the alternative it has in mind: multiple terminal windows or tmux, where, in the project's own words, there is "no GUI, no automatic git isolation" and you "manage worktrees, branches, and merges by hand." That is the gap: not the agent, but the orchestration around it. The app is a TypeScript Electron desktop application, MIT licensed, with macOS and Linux builds and no separate subscription.

How the worktree mechanism actually works

The README describes a four-step sequence when a task is created. Parallel Code creates a new git branch from your main branch, sets up a git worktree so the agent works in a separate directory, symlinks node_modules and other gitignored directories into that worktree, and then spawns the AI agent inside it. Merging back to main happens from the sidebar when you are satisfied with the result.

The symlink step is the part worth thinking about. A fresh worktree has no installed dependencies, and reinstalling them per agent would be slow, so the app links the existing directories instead. That is a reasonable trade, but it means the agent's worktree and your main checkout share the same node_modules inode. Anything an agent does to that directory, including running a package manager, affects your primary checkout too. The README presents this as a convenience; it is also the sharpest edge in the design.

Around that core, the app layers a diff viewer with inline review comments and per-commit navigation, a steps tracking panel that writes to .claude/steps.json, per-task notes that can be sent to the agent as a prompt, shell terminals scoped to the worktree, and a PR CI status watcher that fires a desktop notification when GitHub checks settle. There is also an AI Arena mode for racing agents head to head, and a coverage radar showing per-file test-coverage badges in the Changed Files panel. Two escape hatches matter for adoption: Direct mode works on the main branch without isolation, and the app supports folders that are not a git repository at all.

Installing Parallel Code and dispatching a first task

There is no package-manager install for the application itself. The README points to the releases page and names the artefacts: a universal .dmg for macOS, and .AppImage or .deb for Linux. Download the one for your platform and install it the way you normally install a desktop application.

Before the app is useful you need at least one supported agent CLI on your PATH. The README lists Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, and Copilot CLI. Install whichever you already use; the app spawns them rather than bundling them.

If you prefer to build from source, the README gives this sequence, which requires Node.js v18 or later:

git clone https://github.com/johannesjo/parallel-code.git
cd parallel-code
npm install
npm run dev

The dev script compiles the Electron main process, bundles the MCP server, starts Vite on port 1421, waits for it, and launches Electron against the dev server URL. Expect a desktop window to open once the wait-on step completes.

With the app running, point it at a git repository and create a task. The README's flow is: create the task, let the agent work in its own branch and worktree, review the diff, then merge from the sidebar with the merge shortcut. The default new-task shortcut is Ctrl+N (Cmd+N on macOS), and Ctrl+Shift+M merges the task to main. The README notes that Ctrl means Cmd on macOS throughout the shortcut table.

A task that needs a container can use a project-specific Dockerfile. According to the README, dropping a .parallel-code/Dockerfile into the project makes tasks run inside it. That is opt-in per repository, not a global setting.

The Antigravity exception and other real limitations

The README documents one failure mode outright, and it is worth reading before you plan around it. Antigravity (agy) signs in interactively and caches credentials in the OS keyring. A Linux container cannot reach that keyring because it needs a secret-service daemon the agent container does not run, and agy has no API-key fallback. The consequence, stated in the README, is that Docker-isolated Antigravity tasks cannot authenticate; the recommendation is to run Antigravity as a native, non-Docker task. The bundled image still ships the agy binary and shares ~/.gemini/antigravity-cli when "Share agent auth" is enabled, so the project is leaving room for a file-based or API-key path later. Today, though, the combination does not work.

Platform coverage is the second constraint. The README lists macOS and Linux only. There is no Windows build documented. If your team is on Windows, this is not the tool, regardless of how well the worktree model fits.

The third limitation is structural rather than documented. Parallel Code does not review code for you. It creates isolation, shows diffs, and merges branches. If an agent produces a plausible but wrong change across ten worktrees, you now have ten diffs to read instead of one. The app reduces the cost of running agents in parallel; it does not reduce the cost of verifying them. Teams that merge agent output without reading the diff will find that parallelism multiplies mistakes at the same rate it multiplies throughput.

Finally, the app creates branches and worktrees in your repository. That is the point, but it means the tool has write access to your git state. The repository includes .gitleaks.toml, a .semgrep/ directory, and lint scripts for secrets and security rules, which suggests the maintainers treat the codebase's own safety seriously; that says nothing about what an agent will do in your worktree.

Parallel Code versus tmux, VS Code extensions and sequential runs

The README's own comparison table names three alternatives and what each lacks. Multiple terminal windows or tmux give you no GUI and no automatic git isolation, so worktrees, branches and merges are yours to manage. VS Code extensions such as Kilo Code and Roo Code are tied to VS Code and, per the README, offer no true parallel worktree isolation between agents. Running agents sequentially processes one task at a time and blocks your workflow while each agent finishes.

The honest difference is where the isolation lives. With tmux you can absolutely run ten agents in ten worktrees; the commands are not secret, and a shell script can do the setup. What you do not get is the review surface: the built-in diff viewer with inline comments, the per-commit navigation, the merge button in a sidebar, and the status panels that show what each agent is doing. Parallel Code is buying you a UI over git worktree plus a diff review workflow. If you already have that workflow scripted and you like your terminal, the marginal gain is smaller than the README's framing suggests.

Against VS Code extensions the distinction is sharper. An extension lives inside the editor and inherits its single-workspace model; Parallel Code is a separate Electron application whose unit of work is a task with its own worktree, so the agents are isolated from each other by construction rather than by convention. That is a genuine architectural difference, not a preference.

One more comparison the README makes implicitly: the app is free and MIT licensed, and the README states there is no extra platform fee. You still pay whatever Claude Code, Codex or Gemini costs you. Parallel Code does not resell model access.

Licence, maintenance and what upgrades cost you

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard permissive position and it means embedding or forking the app is legally straightforward. It does not tell you anything about the licences of the agent CLIs you point it at, which are separate products with their own terms; Parallel Code spawns them, it does not sublicense them. Nothing here is legal advice, and if you plan to redistribute a modified build, read the LICENSE file in the repository rather than this summary.

The repository was last pushed on 2026-08-21, and the most recent release listed is v1.14.5 on the same date, following v1.14.3 on 2026-08-18 and v1.14.2 on 2026-08-13. The release cadence in that window is roughly weekly, and the package.json version field reads 2.0.0 while the published releases are still on 1.14.x, which suggests the next major line is in progress on main rather than shipped. The repository is not archived.

Upgrade cost is the part worth weighing. This is a desktop application, so upgrades are downloads rather than dependency bumps, and the README states that state persists across restarts. The real cost is configuration drift: keyboard shortcuts are configurable with per-agent presets, there are ten themes, and there is a choice between Claude Code and MiniMax M2.7 for the inline code Q&A feature. Each of those is a setting a teammate can change. If you standardise on Parallel Code across a team, decide early whether those settings live in a shared config or stay local.

Editorial conclusion

Adopt Parallel Code if you already run Claude Code, Codex or Gemini from a terminal on macOS or Linux and want the isolation handled for you, especially if you work on several features at once and review diffs before merging. Skip it if you are on Windows, if you need Antigravity inside Docker isolation, or if you would rather not give a desktop app control over branch and worktree creation. Verify first that your repository tolerates symlinked node_modules and that your team is comfortable with an agent committing to a branch that a human later merges.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes