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: 1. Main Claude Code instance (your terminal) runs hook on Task tool 2. Hook calls `subprocess.Popen(["claude", "-p", "prompt"])` 3. A NEW Claude Code instance spawns as child process 4. Child runs independently, reads/writes to coordination DB 5. 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 1. User runs `claude` in terminal 2. Claude Code loads hooks from `.claude/settings.json` 3. User says "spawn a research agent" 4. Claude uses Task tool 5. PreToolUse hook fires, checks resources 6. Hook spawns `claude -p "research..."` as subprocess 7. Hook stores PID in PostgreSQL 8. Child agent runs, writes output to `.claude/cache/agents/<id>/` 9. Child completes, broadcasts "done" to PostgreSQL 10. 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