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');

Completion Detection

Agents signal completion by creating a marker file:

touch .claude-task-complete

This enables:

• cpo to detect task completion
• Wave coordination (wait for all tasks before next wave)
• Status reporting

Execution Patterns

Method	Best For	Parallelism
cpo CLI	Standard workflow, most users	True parallel with wave deps
Claude Code SDK	CI/CD, custom orchestration	Fully programmable

Tips for Success

1. Validate first: Always run cpo validate before cpo run
2. Start small: Test with 2-3 parallel agents before scaling up
3. Monitor resources: Limit concurrent agents based on machine capacity
4. Check logs: Review logs/task-*.log for debugging
5. Run integration: Use /parallel-integrate after all tasks complete

Output Files

After execution:

parallel/TS-0042-inventory-system/
  logs/
    task-001.log          # Agent output
    task-002.log
    ...
  report.json             # Execution summary
  integration-report.md   # Generated by /parallel-integrate

Related

• parallel-agents skill: Overall workflow and directory structure
• parallel-decompose skill: Creating tasks before execution
• parallel-prompt-generator skill: Generate prompts from task specs
• agent-tools skill: Tool permissions (for granular control)
• /parallel-integrate command: Post-execution verification