Claude Parallel Agent Harness

A reusable harness for orchestrating multiple Claude Code agents to execute complex, multi-step projects autonomously. Each agent picks up tasks from a shared backlog, works in an isolated git worktree, and merges completed work back to the main branch.

How It Works

run-parallel.sh 3
  ├── agent-1 (autonomous loop)
  ├── agent-2 (autonomous loop)
  └── agent-3 (autonomous loop)
       │
       ├── Pick next task from backlog/
       ├── Claim atomically (mkdir lock)
       ├── Create isolated git worktree + branch
       ├── Spawn FRESH Claude Code instance
       ├── On success → commit, merge to master
       └── Loop until all tasks done

Key Design Principles

• Fresh context per task — each Claude Code invocation starts clean, no context window exhaustion
• Filesystem-based coordination — no database or message broker needed, just mkdir locks
• Cross-iteration memory — progress.txt carries learnings between agent invocations
• Git worktree isolation — each agent works in its own worktree, no branch conflicts
• Resilient to cutoffs — tasks are self-contained, can be re-run from where they left off

Inspired by:

• Building a C Compiler with Parallel Claude Agents
• Ralph: Autonomous AI Agent Loop

Quick Start

1. Clone and customize

git clone https://github.com/dancompton/claude-parallel-harness-example.git
cd claude-parallel-harness-example

Edit these files for your project:

File	Purpose
.claude/agent-harness/AGENT_GUIDE.md	Codebase context injected into every agent (tech stack, file structure, coding standards)
.claude/agent-harness/STRATEGY.md	Your project plan broken into phases and tasks
.claude/agent-harness/tasks/backlog/*.md	Individual task files (one per task)

2. Create your tasks

Each task is a markdown file in tasks/backlog/. See the example tasks for the format:

# Task 01 — Short Description

## Phase: 1 — Foundation
## Priority: High
## Dependencies: None           # or "Task 01" / "Tasks 01, 02"

## Objective
What to accomplish.

## Steps
1. First step
2. Second step

## Files to Modify
- path/to/file.go

## Files to Create
- path/to/new_file.go

## Verification
go build ./...
go test ./...

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

3. Run

# Launch 3 parallel agents (fire-and-forget)
bash .claude/agent-harness/scripts/run-parallel.sh 3

# Or single agent
bash .claude/agent-harness/scripts/run-agent.sh agent-1

# Or one specific task
bash .claude/agent-harness/scripts/run-single-task.sh 01-example-task

# Or interactive mode (you guide the agent)
bash .claude/agent-harness/scripts/run-interactive.sh 01-example-task

4. Monitor

# Status dashboard
bash .claude/agent-harness/scripts/status.sh

# Watch logs
tail -f .claude/agent-harness/logs/agent-*.log

# Check cross-iteration memory
cat .claude/agent-harness/progress.txt

Directory Structure

.claude/
├── settings.local.json              # Permission whitelist for Claude Code
└── agent-harness/
    ├── README.md                    # Detailed harness documentation
    ├── AGENT_GUIDE.md               # YOUR codebase context (customize this)
    ├── STRATEGY.md                  # YOUR project plan (customize this)
    ├── progress.txt                 # Cross-iteration memory (auto-managed)
    ├── scripts/
    │   ├── run-parallel.sh          # Launch N agents in parallel
    │   ├── run-agent.sh             # Single autonomous agent loop
    │   ├── run-single-task.sh       # One-shot task runner
    │   ├── run-interactive.sh       # Interactive mode
    │   ├── status.sh                # Task status dashboard
    │   └── reset.sh                 # Reset all tasks to backlog
    ├── tasks/
    │   ├── backlog/                 # Tasks ready to be claimed
    │   ├── in_progress/             # Tasks currently being worked on
    │   ├── completed/               # Successfully finished tasks
    │   ├── blocked/                 # Failed or blocked tasks
    │   └── .locks/                  # mkdir-based atomic locks
    ├── logs/                        # Agent execution logs
    ├── context/                     # Optional shared context files
    └── verification/                # Optional verification scripts

Configuration

Environment Variables (in run-agent.sh)

Variable	Default	Description
BRANCH_PREFIX	task/	Git branch prefix for task branches
MAX_TURNS	150	Max Claude Code turns per task
WAIT_INTERVAL	10	Seconds between empty-task checks
MAX_EMPTY_WAITS	60	Max empty cycles before agent exits (~10 min)

Permission Modes

The scripts use --dangerously-skip-permissions by default. For production use, consider:

# More restrictive — prompts for dangerous operations
--permission-mode acceptEdits --allowedTools "Bash,Read,Write,Edit,Glob,Grep"

Or customize .claude/settings.local.json with specific permission grants.

Requirements

• Claude Code CLI installed
• Claude Max plan (for subscription auth) or ANTHROPIC_API_KEY set
• Git repository initialized

License

MIT