parallel-lanes for Claude Code

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
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

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 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, you get a report, and Claude
   offers to open a PR. It never pushes, opens a PR, or merges without a separate yes.

If a run stops (a budget cap, a question it can't settle, or a closed session), the next
session lists it, and you can resume with one word. Finished tasks are skipped.

How a run works

1. Assess. scripts/derive-lanes groups the tasks into lanes (at most
   min(5, CPU cores + 2)), a prelude (shared groundwork that runs first), and a join
   (tasks that need the merged result). Plans with only 1-2 tasks are handed back to
   Superpowers.
2. Manifest. Claude writes a JSON manifest covering lanes, model tier per task
   (standard, sonnet, or light; security-sensitive tasks are always standard),
   project commands, commit rules taken from your CLAUDE.md, and budgets.
3. Dry run and consent. The workflow validates the manifest without spawning anything,
   and Claude shows the table. "Just run it" and auto mode do not skip it.
4. Execute. The run takes a launch lock (a second session cannot reset it), then
   scripts/setup also locks the project checkout in git mode (two runs cannot switch one
   checkout to their feature branches), creates the feature branch and lane worktrees, saving any changes it has
   to discard under a git ref first. The phases run: pre-flight conflict check, prelude,
   lanes in parallel, integration, join, E2E, a final review with three lenses and one fix
   round, and a verify step that reruns the project checks (every lane's checks included) and any stale E2E or
   post-integration check on the exact revision delivered. The full pre-flight stops the run,
   naming the move that fixes it, when a task needs code from a task scheduled after it.
5. Hand-back. The report leads with acceptance: accepted only when every check passed
   on the delivered revision (and ran on committed files, not uncommitted tracked changes), all
   final reviewers judged the same commit, no blocking finding is open, and nothing was deferred;
   otherwise rejected or unverified, with every reason, and the run stays resumable. It
   also covers each task's commits, review rounds, model and token usage, rulings made on
   your behalf, and the E2E result.

Other things to know:

• Autonomy. In autonomous mode (the default), an adjudicator agent settles blocked
  tasks and review deadlocks, capped at 25 rulings per run. In supervised mode, those
  stop the run for you instead. You can switch modes when the table is shown. A task the
  adjudicator parks is deferred, never counted as delivered; security tasks are never
  parked, and allow_deferral: false forbids parking altogether.
• Transient failures (agent errors, missing results) relaunch once automatically.
  Anything substantive stops the run and asks you.
• Where files go. Manifests and ledgers are stored beside the plan, or under
  ~/.claude/parallel-lanes/runs/ (under CLAUDE_CONFIG_DIR when set) when the plan is
  inside the repo. Worktrees go in a
  sibling directory such as <repo>-wt-<run_id>. In git mode the run adds branches to
  your repo, but no run files are written inside the project folder.
• Run tools. Five helpers surround a run: doctor checks the machine and the project
  before a launch, archive-run copies a finished run into the run history, autopsy reports
  where one run's time and tokens went, history compares the archived runs, and cleanup
  removes a finished run's worktrees and branches after writing a restore point. Claude runs
  them for you; reference.md ("Run history", "Autopsy", "Doctor", "Cleanup") documents each.

6. Update or uninstall

• Update: in your clone, run git pull && bash install.sh. It replaces the
  installed skill and does not add the hooks twice. On Windows, a clone made before 1.3.0
  keeps its Windows line endings after the pull: run git rm -r -q --cached . && git reset -q --hard in it once first (it discards local changes in that clone).
• Uninstall: run bash install.sh --uninstall. It removes both hooks (after backing up
  settings), the agent file ~/.claude/agents/parallel-lanes-worker.md, and
  ~/.claude/skills/parallel-lanes. Run records in
  ~/.claude/parallel-lanes/ are kept; delete that folder by hand if you don't want them.

7. Troubleshooting

Layout

License

MIT. See LICENSE.