What is OPC in simple terms?

OPC is an orchestration layer around Claude Code that coordinates multiple agent runs via hooks, skills, scripts, and a shared database; it does not replace Claude Code.

How does OPC coordinate agents?

OPC uses hooks to intercept events, spawns child Claude Code processes, and stores state in PostgreSQL while writing outputs to the cache directory for aggregation.

Do I need to modify Claude Code to use OPC?

No. OPC works through hooks and external files (skills, scripts, database) and does not change Claude Code's internal behavior.

opc-architecture

npx machina-cli add skill parcadei/Continuous-Claude-v3/opc-architecture --openclaw

Files (1)

SKILL.md

2.8 KB

OPC Architecture Understanding

OPC (Orchestrated Parallel Claude) extends Claude Code - it does NOT replace it.

Core Concept

Claude Code CLI is the execution engine. OPC adds orchestration via:

Hooks - Intercept Claude Code events (PreToolUse, PostToolUse, SessionStart, etc.)
Skills - Load prompts into Claude Code
Scripts - Called by hooks/skills for coordination
Database - Store state between Claude Code instances

How Agents Work

When you spawn an agent:

Main Claude Code instance (your terminal) runs hook on Task tool
Hook calls subprocess.Popen(["claude", "-p", "prompt"])
A NEW Claude Code instance spawns as child process
Child runs independently, reads/writes to coordination DB
Parent tracks child via PID in DB

$ claude                         ← Main Claude Code (your terminal)
    ↓ Task tool triggers hook
    ↓ subprocess.Popen(["claude", "-p", "..."])
        ├── claude -p "research..."   ← Child agent 1
        ├── claude -p "implement..."  ← Child agent 2
        └── claude -p "test..."       ← Child agent 3

What OPC Is NOT

OPC is NOT a separate application
OPC does NOT run without Claude Code
OPC does NOT intercept Claude API calls directly
OPC does NOT modify Claude Code's internal behavior

What OPC IS

OPC IS hooks that Claude Code loads from .claude/hooks/
OPC IS skills that Claude Code loads from .claude/skills/
OPC IS scripts that hooks/skills call for coordination
OPC IS a database backend for state across Claude Code instances

Key Files

.claude/
├── hooks/           ← TypeScript hooks that Claude Code runs
├── skills/          ← SKILL.md prompts that Claude Code loads
├── settings.json    ← Hook registration, Claude Code reads this
└── cache/           ← State files, agent outputs

opc/
├── scripts/         ← Python scripts called by hooks
├── docker-compose.yml ← PostgreSQL, Redis, PgBouncer
└── init-db.sql      ← Database schema

Coordination Flow

User runs claude in terminal
Claude Code loads hooks from .claude/settings.json
User says "spawn a research agent"
Claude uses Task tool
PreToolUse hook fires, checks resources
Hook spawns claude -p "research..." as subprocess
Hook stores PID in PostgreSQL
Child agent runs, writes output to .claude/cache/agents/<id>/
Child completes, broadcasts "done" to PostgreSQL
Parent checks DB, reads child's output file

Remember

Every "agent" is just another claude -p process
Hooks intercept events, they don't create new functionality
All coordination happens via files and PostgreSQL
Claude Code is always the execution engine

Source

git clone https://github.com/parcadei/Continuous-Claude-v3/blob/main/.claude/skills/opc-architecture/SKILL.mdView on GitHub

Overview

OPC (Orchestrated Parallel Claude) extends Claude Code by adding hooks, skills, scripts, and a shared database to coordinate multiple agent runs. It does not replace Claude Code; it orchestrates parallel Claude Code instances by intercepting events and storing state across runs.

How This Skill Works

Claude Code runs as the execution engine. OPC injects orchestration via hooks and skills loaded from .claude, while scripts coordinate actions. A parent process spawns child Claude Code instances through subprocess.Popen, with each child reading/writing to a central PostgreSQL database and producing outputs in the .claude/cache directory; the parent tracks child PIDs and aggregates results.

When to Use It

You need to spawn multiple parallel agents (e.g., research, implement, test) triggered by a single user command.
You want PreToolUse hooks to verify resources before tools are invoked.
You require persistent state and coordination across Claude Code instances using a database.
You load prompts as skills under .claude/skills/ to standardize agent behavior.
You need a centralized view of agent outputs and completion status via PostgreSQL and cache files.

Quick Start

Step 1: Ensure .claude/hooks/, .claude/skills/, and opc/ are present and settings.json registers the hooks.
Step 2: Load a responsive skill prompt into .claude/skills and configure a spawn action via the Task tool.
Step 3: Use the Task tool to spawn an agent; monitor PostgreSQL for PID entries and check .claude/cache/agents for outputs.

Best Practices

Define clear, task-specific prompts in .claude/skills and keep them versioned.
Keep hooks idempotent and resilient to restarts to avoid duplicate work.
Store coordination state in PostgreSQL with proper indexing for fast lookups.
Organize child outputs under .claude/cache/agents/<id>/ for traceability.
Monitor resource usage and implement error handling for failed agents with clear retries.

Example Use Cases

Spawn three parallel agents (research, implement, test) for a coding task and aggregate their outputs after completion.
Use PreToolUse hooks to check GPU/RAM availability before launching resource-intensive tasks.
Coordinate long-running analysis by persisting progress in the coordination DB and reading updates from child caches.
Debug an orchestration flow by inspecting PostgreSQL entries and the agent output files in .claude/cache.
Scale orchestration in CI by running multiple agents on different prompts and consolidating results in a single report.

Frequently Asked Questions

Add this skill to your agents