opc-architecture

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

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

```

• 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

• 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

```

.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

```

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//
9. Child completes, broadcasts "done" to PostgreSQL
10. Parent checks DB, reads child's output file

• 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