Parallel Dev: Build an Online Swapmeet

Run 4 Claude Code agents simultaneously on separate branches of your repo.

Introduction

30 Second Summary

When you have a big project to build, working on it piece by piece feels painfully slow. What if you could split the work across multiple AI agents, all building different parts at the same time?

In this project, you will set up a parallel development environment where 3 Claude Code agents work simultaneously on your deliverable. Two developer agents build separate modules while a coordinator agent orchestrates and reviews their work. You'll coordinate them through GitHub Issues and PRs, with you as the human-in-the-middle supervising all lanes.

What You'll Build

You'll watch 3 terminal panes light up as Claude Code builds 2 different modules in parallel while a coordinator agent reviews and orchestrates, then bring all the pieces together into a single working codebase through GitHub PRs and a rebase-based integration strategy.

By the end of this project, you'll have:

  • A task decomposition methodology that lets you break a multi-component deliverable into parallelizable lanes with clear file-ownership boundaries and interface contracts.
  • A 3-lane development environment with 2 developer agents building modules in isolated repo clones and 1 coordinator agent orchestrating reviews and cross-lane dependencies.
  • A GitHub coordination system where Issues define task contracts, PRs deliver code, and @claude mentions enable inter-agent communication and automated review.
  • Secret Mission: A 4th "auditor" lane that automatically reviews each PR for scope violations and quality issues before you even look at it.

Are there any prerequisites?

Yes. You need an active Claude Code subscription (Pro, Max, Team, or Enterprise), the GitHub CLI installed and authenticated, and Git configured on your machine.

You also need a deliverable to build. Bring a multi-component project you want to ship faster.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters for your workflow. This project teaches a methodology, not a specific app. You're bringing your own deliverable and learning how to build it 3-4x faster using parallel AI-assisted development.

Set Up the GitHub Coordination Layer

Set Up Your Harness

Running 3 Claude Code agents in parallel sounds fast, but without a coordination layer those agents are just isolated silos. They cannot communicate, review each other's work, or enforce quality gates.

In this step you will build the coordination backbone: a GitHub repo wired up with claude-code-action for inter-agent messaging, branch protection for quality gates, and a CLAUDE.md that scopes every agent's behavior. You will also create the 3 clone directories that become your development lanes.

In this step, get ready to:
  • Install the claude-code-action GitHub App and create the workflow file.
  • Configure branch protection and a CLAUDE.md coordination file.
  • Clone the repo 3 times into separate lane directories (2 developer lanes + 1 coordinator lane).
Create the GitHub repo and configure claude-code-action

The claude-code-action GitHub App lets Claude Code respond to @claude mentions in Issues and PRs. This is how your lanes will communicate later.

  • Confirm your project codebase has a Git repo with at least one commit.
  • If you already have this repo on GitHub, skip to the next action. If not, create a new GitHub repo from your local project by running:
gh repo create --source=. --push --public

What does this command do?

The --source=. flag tells gh to create a remote repo from your current local directory.

The --push flag pushes all local commits to the new remote immediately. Use --private instead of --public if your code is proprietary.

  • Verify the repo exists on GitHub by running:
gh repo view --web

Your browser opens to the repo page showing your codebase on main.

  • Install the Claude Code GitHub App on your repo by running this command inside Claude Code:
/install-github-app

What is /install-github-app?

This is a built-in Claude Code slash command that installs the Claude Code GitHub App on your repository. It opens a browser window where you authorize the app. Follow the prompts to grant access to your repo.

  • Create the workflow directory by running:
mkdir -p .github/workflows
  • Create the workflow file .github/workflows/claude.yml and paste the following content:
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned, labeled]
  pull_request_review:
    types: [submitted]
jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      actions: read
    steps:
      - uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

What does this workflow do?

This GitHub Actions workflow listens for @claude mentions in issue comments, PR review comments, newly opened issues, and PR reviews.

When triggered, it runs anthropics/claude-code-action@v1 which gives Claude Code access to your repo so it can read context, write code, and respond. The permissions block grants the minimum access needed for Claude to push commits and comment.

  • Set your Anthropic API key as a repo secret by running:
gh secret set ANTHROPIC_API_KEY

This prompts you to paste your API key. Paste it and press Enter. The value is encrypted before being sent to GitHub.

Using OAuth instead of an API key

If your Claude Code subscription uses OAuth authentication, set CLAUDE_CODE_OAUTH_TOKEN as your repo secret instead, and update the workflow to reference that secret name.

  • Commit and push the workflow file by running:
git add .github/workflows/claude.yml
git commit -m "Add claude-code-action workflow"
git push

You should see the push succeed with no errors.

Push rejected?

If you see a rejection, pull any remote changes first with git pull --rebase then push again.

If you see a permissions error, confirm gh auth status shows you authenticated with write access to the repo.

Still stuck? Why can't I push my workflow file to GitHub?

Configure branch protection and CLAUDE.md

Branch protection ensures no lane can push directly to main without review. The CLAUDE.md file tells every Claude Code session how to behave within the lane coordination protocol.

  • Open your repo's branch protection settings in your browser. Navigate to your repo on GitHub, click **Settings**, then **Branches** in the left sidebar.
  • Click **Add branch protection rule** (or **Add rule** if you already have rules).
  • In **Branch name pattern**, type main.
  • Check **Require a pull request before merging**.
  • Under that, set **Require approvals** to 1.
  • Check **Require status checks to pass before merging**.
  • Check **Do not allow bypassing the above settings** to prevent direct pushes.
  • Click **Create** (or **Save changes**) to apply the rule.

Why branch protection for AI agents?

Without branch protection, a lane agent could accidentally push directly to main and overwrite another lane's work. Requiring PRs forces every lane through a reviewable, merge-conflict-aware integration path.

  • Return to your terminal in the project directory. Create the CLAUDE.md file at the repo root and paste the following content:
# Project CLAUDE.md

## Project Architecture
[Learner fills in their project architecture]

## Coding Standards
[Learner fills in coding standards]

## Module Boundaries
[Learner fills in module boundaries and file ownership]

## Lane Coordination Protocol
- Reference the Issue number in all commit messages (e.g., 'feat: implement X (refs #N)')
- Do not modify files outside your assigned scope
- When complete, push your branch and open a PR linking to your Issue
- Use @claude mentions in PR/Issue comments for inter-agent coordination

What is CLAUDE.md?

Every Claude Code session reads CLAUDE.md from the repo root for project-level context. It acts as a shared instruction set that every agent follows.

The first three sections are placeholders for you to fill in with your project's specifics. The Lane Coordination Protocol section is already defined and ensures all agents follow the same commit and PR conventions.

  • Fill in the first three sections of CLAUDE.md with your project's architecture, coding standards, and module boundaries. Be specific about which directories belong to which module.
  • Commit and push CLAUDE.md by running:
git add CLAUDE.md
git commit -m "Add CLAUDE.md coordination file"
git push
  • Now test the GitHub App by creating a test Issue. Run:
gh issue create --title "Test: Verify claude-code-action" --body "Testing the GitHub App integration."

Note the issue number printed in the output (e.g., #1).

  • Before you comment, what do you expect to happen when you mention @claude on this issue?
  • Comment on the issue to trigger the action. Replace 1 with your actual issue number:
gh issue comment 1 --body "@claude ping"

Decompose the Deliverable into Lanes

Your GitHub coordination layer is live and your 3 lane directories are ready. Now comes the critical planning step: deciding exactly what each lane will build or coordinate.

If two lanes touch the same files, you get merge conflicts that negate the entire speed benefit of parallel development. The decomposition step draws boundaries that make parallel work safe.

In this step, get ready to:
  • Analyze your deliverable's module boundaries using Claude Code in Plan Mode.
  • Create 3 GitHub Issues: 2 developer task contracts and 1 coordinator contract.
  • Write per-lane CLAUDE.md override files that scope each agent to its assigned role.
Analyze module boundaries

Before splitting work across lanes, you need to identify which parts of your codebase can be built independently. Claude Code's Plan Mode lets you scope this analysis without making any code changes.

  • Switch to a terminal tab that is not one of your 3 lane panes. Navigate into your main working copy of the repo (not a lane clone) by running:
cd ~/Desktop/[[REPO_NAME="your-repo-name"]]
  • Launch Claude Code by running:
claude
  • Enter Plan Mode by pressing Shift+Tab (or typing /plan). This puts Claude into an analysis-only mode where it reasons about structure without editing files.
  • Ask Claude to analyze your module boundaries. Paste a prompt like this:
Analyze this project's architecture. Identify 2 modules that can be built independently in parallel.
For each module, tell me:
1. Which directories/files it owns exclusively
2. What interface it exposes to other modules (function signatures, types, API shapes)
3. Which other modules it depends on

The goal: no two modules should own the same file.

What is Plan Mode doing here?

Plan Mode prevents Claude from writing any code. It outputs a structured analysis you can review and refine before committing to a decomposition.

If Claude suggests only 1 module, ask it to split further. If it suggests more than 2, ask it to merge related concerns. The target is exactly 2 developer modules plus 1 coordinator role.

  • Review Claude's output. For each of the 2 modules, confirm that no two modules claim the same files.
  • Once you are satisfied with the 2-module split, update your CLAUDE.md file's Module Boundaries section with the documented boundaries. Open CLAUDE.md in your editor and replace the placeholder text under ## Module Boundaries with a summary of each module's name, owned directories/files, and interface contract.
  • Save CLAUDE.md.

Confirm that CLAUDE.md now has your 2 developer modules documented by opening it and scanning for the boundaries section.

The interface-first pattern

If your modules share types, constants, or API contracts, create those shared files on main now, before any lane begins work. This prevents two lanes from defining the same interface differently.

For example, if both developer lanes need a UserProfile type, define it in a shared file now and push it to main. Both lanes will inherit it when they branch off.

🙋‍♀️ Claude suggesting too many shared files?

If most of your code seems shared, your modules may be too tightly coupled for parallel work. Ask Claude to redraw boundaries at a higher level (e.g., by feature or by layer) until each module owns at least 60-70% unique files.

help me redraw my module boundaries so each developer lane has mostly unique files

Create GitHub Issues as task contracts

Each lane needs a clearly defined contract before any agent starts writing code. GitHub Issues serve as that contract: they define what the lane builds, what files it owns, and when it is done.

  • First, create the lane labels in your repo by running these commands:
gh label create lane-1 --color 0E8A16
gh label create lane-2 --color 1D76DB
gh label create coordinator --color 5319E7
  • Verify the labels were created by running:
gh label list

You should see lane-1, lane-2, and coordinator in the output alongside any existing labels.

  • Now create the Issue for Lane 1. Use this template, replacing the placeholders with your module-1 details from the analysis above:
gh issue create \
  --title "Lane 1: [[MODULE1_NAME="your module-1 name"]]" \
  --label "lane-1" \
  --body "## Module Scope
[[MODULE1_DESCRIPTION="Describe what this module does"]]

## Owned Files/Directories
- [[MODULE1_FILES="list each file or directory this lane owns exclusively"]]

## Interface Contract
[[MODULE1_INTERFACE="function signatures, types, or API shapes this module exposes"]]

## Acceptance Criteria
- [[MODULE1_CRITERIA="list what done looks like for this module"]]

## Dependencies
- [[MODULE1_DEPS="list which other lane Issues this depends on, or None"]]"

What makes a good Issue contract?

The Owned Files/Directories section is the most important. It tells the agent exactly which files it can create or modify. No ambiguity here prevents merge conflicts later.

The Interface Contract section defines what this module promises to other modules. Think of it as the public API: function signatures, exported types, or endpoint paths.

  • Confirm Issue #1 was created by running:
gh issue view 1

You should see the full body of your Issue with the lane-1 label attached.

  • Create the remaining 2 Issues. First, Issue #2 for the second developer lane using the same template structure with label lane-2 and module-2 details.
gh issue create \
  --title "Lane 2: [[MODULE2_NAME="your module-2 name"]]" \
  --label "lane-2" \
  --body "## Module Scope
[Fill in module-2 scope]

## Owned Files/Directories
[Fill in module-2 files]

## Interface Contract
[Fill in module-2 interface]

## Acceptance Criteria
[Fill in module-2 criteria]

## Dependencies
[Fill in module-2 deps]"
  • Now create the coordinator Issue. This one defines the orchestration role rather than a code module:
gh issue create \
  --title "Coordinator: Review and orchestrate lanes" \
  --label "coordinator" \
  --body "## Role
You are the coordinator agent. You do NOT write application code.

## Responsibilities
- Review PRs from lanes 1 and 2 for scope violations
- Verify interface contracts are implemented correctly
- Post review comments on PRs with specific feedback
- Flag cross-lane dependency issues via Issue comments

## Acceptance Criteria
- All developer PRs have at least one review comment from you
- No scope violations remain unaddressed"
gh issue list

You should see 3 open Issues, each with its own label. Confirm no two developer Issues list the same files in their Owned Files section.

Issue creation failed with a label error?

The --label flag requires the label to already exist in the repo. If you see an error, run gh label list to confirm the lane labels are present. Re-run the gh label create commands from earlier if any are missing.

help me debug my gh issue create command that failed

Create per-lane CLAUDE.md overrides

Each lane directory needs its own scoping file that tells Claude Code exactly which Issue to work on and which files it can touch. These override files live in a .claude/ directory on main so every clone inherits them.

  • Create the .claude/ directory by running:
mkdir -p .claude
  • Create the Lane 1 scope file by running:
cat > .claude/lane-1.md << 'EOF'
# Lane 1 Scope
You are working on Issue #1. You own files in [[LANE1_DIR="module-1 directory path"]]. Do NOT modify files outside your scope. Reference Issue #1 in all commit messages. When you complete your task, push your branch and open a PR linking to Issue #1.
EOF

What does this scope file do?

When you copy this file into a lane's clone directory later, Claude Code reads it as additional context. The explicit ownership boundary ("Do NOT modify files outside your scope") prevents the agent from wandering into another lane's territory.

The Issue reference gives Claude a link back to the full contract with acceptance criteria, so it knows when the work is done.

  • Create the Lane 2 and coordinator scope files by running:
cat > .claude/lane-2.md << 'EOF'
# Lane 2 Scope
You are working on Issue #2. You own files in [[LANE2_DIR="module-2 directory path"]]. Do NOT modify files outside your scope. Reference Issue #2 in all commit messages. When you complete your task, push your branch and open a PR linking to Issue #2.
EOF
cat > .claude/coordinator.md << 'EOF'
# Coordinator Scope
You are working on Issue #3. You are the coordinator agent. Do NOT write application code. Your job is to review PRs from lanes 1 and 2, check for scope violations, verify interface contracts, and post review comments. Reference Issue #3 in all commit messages.
EOF
  • Verify all 3 lane files were created by running:
ls .claude/

You should see lane-1.md, lane-2.md, and coordinator.md listed.

  • Commit and push everything to main so all 3 clones can pull these files later:
git add CLAUDE.md .claude/
git commit -m "docs: add module boundaries and per-lane scope files"
git push origin main

Before you check the result, what do you think you will see if you run gh issue list now? How many Issues, and what labels?

  • Verify your full decomposition by running:
gh issue list --label lane-1 && gh issue list --label lane-2 && gh issue list --label coordinator

You should see exactly one Issue per label: two developer modules and one coordinator. No two developer Issues should claim the same files.

Don't see all 3 Issues?

Run gh issue list --state all to check if any were accidentally closed. If an Issue is missing entirely, re-run the gh issue create command for that lane.

help me verify my 3 lane Issues are correctly set up

Your deliverable is now cleanly organized into 3 lanes: 2 developer modules with exclusive file ownership and 1 coordinator role. Each has a GitHub Issue defining its scope and a lane-specific scope file ready to guide Claude Code. Next up, you will launch Claude Code in all 3 lanes simultaneously and start building in parallel.

Secret mission

The Auditor Lane

With 4 lanes producing code simultaneously, manual review becomes the bottleneck. In this extension, you'll add a 5th "auditor" lane that runs Claude Code in read-only review mode, automatically reviewing each PR as it comes in. This shifts quality feedback left, catching issues before you even look at them.

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs locally and on GitHub's free tier, so there are no ongoing cloud costs. The only recurring cost would be Claude Code tokens if you leave the auditor session actively polling for new PRs.

Resources you used:

  • 5 local clone directories (project-lane-1/ through project-lane-4/, project-auditor/).
  • GitHub repo with .github/workflows/claude.yml, .github/workflows/claude-review.yml, CLAUDE.md, and lane config files.
  • claude-code-action GitHub App installed on your repo.
  • Active Claude Code session running in the project-auditor/ directory.

Keep everything running

No action needed. Choose this if you plan to reuse this parallel development setup for your next deliverable.

  • Your repo, workflows, and CLAUDE.md templates stay in place. They are ready to use the next time you decompose a project into lanes.
  • The lane clone directories remain on disk. Delete them individually when you no longer need them as reference.
  • The auditor session in project-auditor/ continues to consume tokens while running. Stop it with Ctrl+C if you are not actively opening new PRs.

Pause - I'll come back to this later

Stop running processes and free up disk space from the clone directories, but keep your repo and workflow templates on GitHub for next time.

  • In the terminal running the auditor session, press Ctrl+C or Escape to stop Claude Code.
  • Remove the 5 clone directories to reclaim disk space by running:
rm -rf project-lane-1 project-lane-2 project-lane-3 project-lane-4 project-auditor

On Windows, run:

Remove-Item -Recurse -Force project-lane-1, project-lane-2, project-lane-3, project-lane-4, project-auditor
  • Your GitHub repo, workflows, and CLAUDE.md templates remain on GitHub. Next time you need parallel lanes, clone the repo fresh and follow the same process.

Delete - I don't want to use this again

Remove all project resources and start fresh. This deletes your local clones, the GitHub repo, and the installed GitHub App.

  • In the terminal running the auditor session, press Ctrl+C or Escape to stop Claude Code.
  • Remove all 5 clone directories:
rm -rf project-lane-1 project-lane-2 project-lane-3 project-lane-4 project-auditor

On Windows, run:

Remove-Item -Recurse -Force project-lane-1, project-lane-2, project-lane-3, project-lane-4, project-auditor
  • Uninstall the claude-code-action GitHub App. Go to your GitHub account Settings, select Applications, open the Installed GitHub Apps tab, click Configure next to Claude Code, then select Uninstall.
  • Delete the GitHub repo. You need the delete_repo scope first. Run:
gh auth refresh -s delete_repo
  • Then delete the repo by running:
gh repo delete --yes

What does this command do?

Running gh repo delete without a repository argument targets the repo in your current directory. The --yes flag skips the interactive confirmation prompt.

  • Remove the ANTHROPIC_API_KEY secret from your repo settings (if you did not delete the repo). Go to your repo on GitHub, click Settings, select Secrets and variables, then Actions. Click the trash icon next to ANTHROPIC_API_KEY to delete it.

That's a Wrap!

That's a Wrap!

Nice work! You just built a complete parallel development methodology where 4 Claude Code agents worked simultaneously on your deliverable, coordinated through GitHub Issues and PRs, with you as the human-in-the-middle supervising every lane.

You've learned how to:

  • Set up a GitHub coordination layer with anthropics/claude-code-action@v1 for inter-agent communication via @claude mentions in Issues and PRs.
  • Decomposed a deliverable into 4 parallel lanes with clear file ownership boundaries, launched concurrent Claude Code sessions scoped by lane-specific CLAUDE.md files, and executed the HITM supervision loop to review, course-correct, and approve work across all lanes simultaneously.
  • Integrated all 4 lanes back to main using sequential rebase-and-merge through PRs with automated Claude Code review, resolving conflicts at integration time rather than hiding them.
  • (Secret Mission) Added a 5th auditor lane that continuously reviews PRs for scope violations, interface contract compliance, and code quality issues.

Ready to quiz yourself?