parallel-execution

Parallel Execution

Execute multiple Claude Code agents in parallel using the cpo (Claude Parallel Orchestrator) CLI.

Primary Method: cpo CLI

The cpo tool handles all execution complexity: git worktrees, wave dependencies, and progress monitoring.

Installation

pip install claude-parallel-orchestrator
# or
pipx install claude-parallel-orchestrator

Commands

Command	Description
cpo validate <dir>	Validate manifest structure and prompts
cpo run <dir>	Execute all waves (respects dependencies)
cpo status <dir>	Check execution status

Basic Workflow

# 1. Validate before execution
cpo validate parallel/TS-0042-inventory-system/

# 2. Execute parallel agents
cpo run parallel/TS-0042-inventory-system/

# 3. Monitor progress (in another terminal)
cpo status parallel/TS-0042-inventory-system/

What cpo run Does

1. Validates manifest.json structure and prompt files
2. Creates git worktrees for each task (isolated workspaces)
3. Launches agents in parallel (respects wave dependencies)
4. Monitors progress with live output
5. Collects results in logs/ and report.json

Wave Execution

Tasks execute in waves based on dependencies:

Wave 1: task-001, task-002, task-003  (parallel - no deps)
         ↓ wait for completion
Wave 2: task-004, task-005            (parallel - depend on Wave 1)
         ↓ wait for completion
Wave 3: task-006                      (sequential - depend on Wave 2)

Each wave waits for all tasks in the previous wave to complete before starting.

Agent Permissions

Agents run with --dangerously-skip-permissions because they're isolated in worktrees:

• Each agent runs in its own git worktree
• Agents can only affect files in their workspace
• Main branch remains protected until explicit merge

Alternative: Claude Code SDK

For programmatic orchestration in CI/CD or custom workflows:

// orchestrator.ts
import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';
import { readdir, readFile } from 'fs/promises';
import { join } from 'path';

async function runParallelTasks(parallelDir: string) {
  const tasksDir = join(parallelDir, 'tasks');
  const contextFile = join(parallelDir, 'context.md');

  const context = await readFile(contextFile, 'utf-8');
  const tasks = await readdir(tasksDir);

  const agents = tasks
    .filter(f => f.endsWith('.md'))
    .map(async (taskFile) => {
      const taskPath = join(tasksDir, taskFile);
      const taskContent = await readFile(taskPath, 'utf-8');

      const agent = new ClaudeAgent({
        systemPrompt: `You are implementing a task.
                       Context: ${context}
                       Follow contracts in ${parallelDir}/contracts/.`,
      });

      return agent.run(`Execute this task:\n\n${taskContent}`);
    });

  const results = await Promise.all(agents);
  return results;
}

runParallelTasks('parallel/TS-0042-inventory-system');