mcpField
O
opc-architecture

opc-architecture

github.com/parcadeiAgent workflows3.9k497 installsUpdated 39w ago
Repository

About opc-architecture

A skill explaining how Orchestrated Parallel Claude (OPC) extends Claude Code, for developers who need to understand its agent coordination model. It describes how hooks, skills, scripts, and a database coordinate independent Claude Code instances.

Key features

  1. 01Explain OPC's relationship to Claude Code
  2. 02Describe hooks and skills
  3. 03Show how child-process agents launch
  4. 04Explain file and PostgreSQL coordination
  5. 05Outline OPC's key files

Use cases

  1. 01Understand OPC's architecture
  2. 02Trace agent startup and execution
  3. 03Inspect coordination across Claude Code instances

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/parcadei/continuous-claude-v3 --skill opc-architecture

After installing, type/opc-architecturein Claude Code to confirm it loaded.

Details

From the project README

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

Comments

Markdown supported