opc-architecture

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// 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