Retrieved article excerpt
Open article · Retrieved 2026-10-10T21:38:20.297878+00:00
# parallel-lanes for Claude Code
[tests](https://github.com/noderaven/parallel-lanes/actions/workflows/tests.yml?query=branch%3Amain)
A Claude Code skill that runs an approved implementation plan as **parallel lanes** of
tasks. Each lane gets its own git worktree, and every task gets an implementer agent and a
reviewer agent. When the lanes finish, it merges them, runs the project's
test/lint/build commands, runs an optional end-to-end check, and finishes with a final
review. It's built to pair with the [Superpowers](https://github.com/obra/superpowers)
plugin: Superpowers handles brainstorming, specs, and plans, and parallel-lanes takes over
when it's time to execute the plan.
## Why it works
- **Safe parallelism.** Lanes are derived from the plan's file lists and dependencies: tasks
that share files stay in one lane or run first as shared groundwork, and each lane works in
its own git worktree. Integration merges the lanes and reruns every check.
- **Review at every step.** Each task is reviewed independently before the next task in its
lane builds on it, and a final review then looks at the whole branch through three lenses.
- **Evidence, not claims.** `accepted` requires the project's checks to pass at the delivered
commit, the final findings to be settled, and the agent's verify report to match the saved
check evidence. A failure is reported as `rejected`; missing or mismatched evidence as
`unverified`.
- **Recoverable.** A ledger records commits and approvals, so an interrupted run resumes where
it stopped, and an approval whose plan section or spec changed is reviewed again.
- **Built on Superpowers.** Superpowers turns an idea into a spec and a structured plan;
parallel-lanes executes that plan with Superpowers' own implementer and reviewer prompts
(built-in prompts when Superpowers is not installed), adding parallel lanes, integration and
verification.
- **What it costs.** It uses more agents, and so more tokens, than a single-agent mode: about
two per task (implement and review) plus about eight per run, before any fix rounds. The
dry-run table shows the exact count before anything starts. There is no measured speedup
claim against sequential execution yet.
---
## 1. Prerequisites
| Requirement | Why | Check |
| --- | --- | --- |
| **Claude Code** with the **Workflow** tool (multi-agent workflows) | Runs the orchestrator `run.workflow.js` | In a Claude Code session, ask: "Do you have the Workflow tool?" |
| **bash** (Git Bash on Windows) | Installer, hooks, helper scripts | `bash --version` |
| **git** 2.31 or later (2.38 or later recommended) | Worktrees, branches, merges | `git --version` |
| **jq** 1.6 or later | Installer and SessionStart hook | `jq --version` |
| **Python** 3.8 or later, as `python3`, `python`, or `py -3` | Lane planning, setup, ledger, reports | `bash scripts/find-python` in the clone prints the one it uses |
| *Optional:* **node** 22 or later | Only for running the test suite | `node --version` |
| *Recommended:* **Superpowers** plugin (tested with 6.4.2; 7.0.0 ships the same prompts) | Supplies the per-task implementer and reviewer prompts | See step 3 |
Platforms: macOS, Linux, and Windows 11. CI runs the test suite on all three, with the stock
bash 3.2 on macOS, so no newer bash is needed. On Windows 11, Claude Code installed natively
works with Git for Windows (see [Windows](https://github.com/noderaven/parallel-lanes#windows) below), and Claude Code inside **WSL**
works as on Linux.
Without the Workflow tool, the skill steps aside and recommends a normal Superpowers
execution mode instead. Without Superpowers, it still runs, but agents use simpler
built-in prompts.
### Installing missing tools
macOS (Homebrew):
```
brew install git jq python node
```
Debian or Ubuntu:
```
sudo apt update && sudo apt install -y git jq python3 nodejs
```
Fedora:
```
sudo dnf install -y git jq python3 nodejs
```
The test suite needs Node 22 or later (`node --version`). If your distribution's `nodejs`
package is older, install a current release from <https://nodejs.org> instead; the skill
itself does not use Node.
### Windows
Native Windows 11 support is verified by complete runs on a real Windows machine, in both git
mode and shadow mode, and a Windows CI job runs the test suite. Claude Code inside WSL works
too: install it there and follow the Linux steps.
- **Git for Windows is required.** With it installed, Claude Code runs its Bash tool and
hooks in Git Bash, and the skill's scripts run there too. Without it Claude Code falls back
to PowerShell, and PowerShell-only setups are not supported.
- **Install the tools** from PowerShell or a Command Prompt, then open a new Git Bash
window so PATH picks them up:
```
winget install Git.Git
winget install jqlang.jq
winget install Python.Python.3.12
winget install OpenJS.NodeJS.LTS
```
Node is optional (tests only; Node 22 or later). Any Python 3.8 or later works: the skill looks for
`python3`, then `python`, then `py -3`, and skips the Microsoft Store `python3` stub.
- **Git in another place:** the skill finds Git Bash on PATH (also through the `Git\cmd` folder
the Git installer puts there) or under `C:\Program Files\Git`.
If Git is installed somewhere else, set the Windows environment variable
`CLAUDE_CODE_GIT_BASH_PATH` to its `bash.exe` (for example `D:\Tools\Git\bin\bash.exe`);
Claude Code reads the same variable. The skill never uses the WSL `bash.exe` in
`C:\Windows\System32`.
- **Long paths:** worktree paths can pass Windows' 260-character limit. Turn on Git's long
path support once:
```
git config --global core.longpaths true
```
The skill does not change your git config for you. Git's setting covers only git. If
another tool (Python, a build tool) later reports a path that is too long, turn on the
Windows switch too, from PowerShell run as Administrator, then sign out and back in:
```
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
```
(The same switch is the Group Policy "Enable Win32 long paths", and the python.org
installer's "Disable path length limit" sets it.) Keeping projects in a short path such
as `C:\src\project` usually avoids the limit altogether.
- **Run the installer from Git Bash** (`bash install.sh`, section 2). `~/.claude` is
`%USERPROFILE%\.claude`. The repo's `.gitattributes` keeps every file's line endings LF
whatever your `core.autocrlf` setting, so a fresh clone works as is.
- **Symlinks:** parallel-lanes does not need Windows Developer Mode, and turning it on is
not recommended (it also relaxes other protections). Without it, Git cannot create
symbolic links, so for a non-git folder that holds symlinks use a git repo rather than
shadow mode.
- **Antivirus scanning:** Windows Defender scans every file the lanes write, which slows
checkouts and test runs. Excluding the worktree folders (`<repo>-wt-<run_id>` next to
your project) from real-time scanning speeds runs up, but those files are then not
scanned; that is your call, and a managed machine may not allow it.
- Run files under `~/.claude/parallel-lanes/` are private to your user through your profile
folder's permissions; the POSIX modes the scripts set have no effect on Windows.
---
## 2. Install the skill
1. Clone the repo:
```
git clone https://github.com/noderaven/parallel-lanes.git
cd parallel-lanes
```
2. Run the installer:
```
bash install.sh
```
On Windows, run both steps in Git Bash. The installer checks for jq, git, and a working
Python 3.8 or later first. Then it does four things:
- Copies the skill (without `.git`) to `~/.claude/skills/parallel-lanes`. The clone
can be deleted afterwards, or kept for updates.
- Installs the `parallel-lanes-worker` agent type to
`~/.claude/agents/parallel-lanes-worker.md`. Runs use it to give each agent a smaller
context, and fall back to the default agent type without it.
- Backs up `~/.claude/settings.json` (to `settings.json.bak.<timestamp>`), then adds two
hooks without touching your other settings:
- **SessionStart**: tells each new, cleared, or compacted session that parallel-lanes
is the default plan executor, and lists any interrupted runs so you can resume them.
- **PostToolUse (Skill)**: shows a notice with the installed version, such as
"parallel-lanes v1.1.0 invoked", when the skill fires.
- Checks for Superpowers and tells you if it's missing.
If you use a custom config directory, run it with that directory instead:
`CLAUDE_CONFIG_DIR=/path/to/config bash install.sh`.
3. **Restart Claude Code** so the hooks load. Running `/clear` in an open session also
works.
---
## 3. Install Superpowers (recommended)
Skip this if the installer didn't warn you about it. Inside Claude Code, run:
```
/plugin marketplace add obra/superpowers
/plugin install superpowers@superpowers-dev
```
Then restart Claude Code. parallel-lanes finds Superpowers automatically at run time. No
configuration is needed.
---
## 4. Verify
1. The files are in place:
```
ls ~/.claude/skills/parallel-lanes/SKILL.md
```
2. The hooks are registered (you should see `session-start.sh` and `notice.sh`):
```
jq '.hooks.SessionStart, .hooks.PostToolUse' ~/.claude/settings.json
```
3. In a new Claude Code session, ask: "Is the parallel-lanes skill available?"
4. Optional: run the test suite:
```
cd ~/.claude/skills/parallel-lanes && node tests/run-tests.mjs
```
5. Optional: to make parallel-lanes the default even more firmly, add this paragraph to
`~/.claude/CLAUDE.md`. The SessionStart hook already covers this, so it isn't required.
> In the main session, when executing approved implementation plans, parallel-lanes is
> the default and takes precedence over superpowers' execution options. Use
> superpowers' Subagent-driven or Native only when parallel-lanes steps aside or I
> explicitly ask for them. Agents running a single task inside a parallel-lanes run must
> not invoke it.
---
## 5. Using it
1. Get a plan. The normal way is to describe what you want built and let Superpowers
handle it: its brainstorming skill turns the idea into a spec, and its writing-plans
skill turns the spec into a plan. You don't write task IDs or headings yourself;
writing-plans numbers the tasks and lists the files each one touches.
You only need to follow a format if you write a plan yourself or bring one from
another tool. parallel-lanes looks for two things in each task:
```
### Task 3: Add the export endpoint
**Files:**
- Create: `src/api/export.py`
- Modify: `src/api/app.py`
- Test: `tests/test_export.py`
```
- A heading of the form `Task <ID>: <title>`, at the same heading level for every
task (a deeper task heading would count as part of the task above it). The ID is a single
token with no spaces, colons, parentheses, or brackets, such as `3`, `T3`, or `T13a`.
- A `**Files:**` block with `Create:`, `Modify:`, or `Test:` lines naming the files in
backticks. This is how it works out which tasks can run in parallel: tasks that
touch the same files go in the same lane.
2. Work inside a git repo with a clean working tree; commit or stash first. For a folder
that isn't a git repo, the skill offers a "shadow repo" that leaves your folder
untouched until you approve copying the results back.
3. When you approve the plan and Claude reaches the "how should I execute this?" step,
parallel-lanes fires automatically. You can also ask directly: "execute this plan with
parallel lanes."
4. Pick **Parallel lanes**, review the dry-run table (tasks, lanes, model tiers, agent
count, budgets), and answer **yes**. Nothing runs before that yes.
5. Watch progress with `/workflows`. When the run finishes, yo