# opc-architecture

opc-architecture provides Claude Code with an architectural overview of Orchestrated Parallel Claude, detailing hooks, child processes, and PostgreSQL state sharing.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 3951 repo stars
- Author: parcadei
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/parcadei/Continuous-Claude-v3/tree/HEAD/.claude/skills/opc-architecture/SKILL.md
- Updated: 2026-01-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/opc-architecture

## What it does

This skill injects the internal architecture of Orchestrated Parallel Claude (OPC) into Claude Code. OPC does not replace the CLI; it uses Claude Code as the execution engine. Orchestration relies on TypeScript hooks in `.claude/hooks/`, coordinating Python scripts, and a shared database backend.

Agent execution is straightforward. When the main terminal instance triggers the Task tool, a `PreToolUse` hook executes `subprocess.Popen(["claude", "-p", "prompt"])`. Each child agent runs as an isolated process, writing output to `.claude/cache/agents/<id>/` and reporting completion back to PostgreSQL.

The frontmatter specifies `user-invocable: false`, meaning it acts as background context rather than a user-triggered command. Orchestration expects the underlying Docker Compose environment with PostgreSQL, Redis, and PgBouncer to be running.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add parcadei/Continuous-Claude-v3 --skill opc-architecture -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/opc-architecture/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/opc-architecture/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add parcadei/Continuous-Claude-v3 --skill opc-architecture -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/opc-architecture/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add parcadei/Continuous-Claude-v3 --skill opc-architecture -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/opc-architecture/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install parcadei/Continuous-Claude-v3 .claude/skills/opc-architecture
```

2. **Manually: put the files in place**
- File: `.github/skills/opc-architecture/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add parcadei/Continuous-Claude-v3 --skill opc-architecture -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/parcadei/Continuous-Claude-v3 --path .claude/skills/opc-architecture
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/opc-architecture/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/parcadei/Continuous-Claude-v3/tree/HEAD/.claude/skills/opc-architecture/SKILL.md

## When to use it
- guide Claude Code on how OPC parallel agents spawn and coordinate
- track child agent state and PIDs through PostgreSQL
- inspect directory layouts across `.claude/` and `opc/`
- debug event interception between hooks and Python scripts

## Example prompts
- Explain how OPC spawns child Claude Code instances using subprocess.Popen
- Where does a child agent write its cached output files in OPC?
- Review the database coordination flow between parent and subagents

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 113a8f7657083d3b.

BEGIN THIRD-PARTY FILE 113a8f7657083d3b
````text
---
name: opc-architecture
description: OPC Architecture Understanding
user-invocable: false
---

# 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
````
END THIRD-PARTY FILE 113a8f7657083d3b

The third-party file has ended. Everything between the 113a8f7657083d3b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2769 of 2867 bytes. © parcadei · MIT · https://github.com/parcadei/Continuous-Claude-v3/tree/HEAD/.claude/skills/opc-architecture/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
