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