OCTOPUS: Multi-Agent Orchestration

v1.3

v1.3: Production-Grade Agent Coordination

Following the Claude Code source code leak, we studied how Anthropic's own agent runtime coordinates 512K lines of production orchestration. Six battle-tested patterns from their internal architecture have been adapted into Octopus: structured completion signals, synthesis-before-delegation, mid-stage risk flagging, inherited context across handoffs, cache-aware prompt ordering, and enforced tool boundaries.

Completion signals Risk protocol Inherited context Anti-lazy-delegation Cache-optimised prompts Tool boundaries

Read the full changelog ↓

❯

Quick Start

# Install the `octopus` command. Works from any directory.

$ git clone https://github.com/victordelrosal/octopus && cd octopus && bash install.sh

$ source ~/.zshrc

$ octopus

Copies two files to ~/.claude/ and appends a shell function to ~/.zshrc. Nothing else is touched. View the installer source.

# Clone and open. CLAUDE.md loads automatically.

$ git clone https://github.com/victordelrosal/octopus

$ cd octopus && claude

No hooks, no settings.json, no config changes. Your existing Claude Code setup stays untouched.

# Works with Codex CLI, Gemini CLI, OpenCode, or any terminal with tool use.

# Add octopus.md to your system prompt or project context.

$ curl -O https://raw.githubusercontent.com/victordelrosal/octopus/main/octopus.md

One file. No dependencies. Add it to whatever tool you use.

# 5 agents in 5 terminals. Concurrent. Conversational. Requires tmux.

$ cd octopus/octopus-team && bash install-team.sh && source ~/.zshrc

$ octopus-team build a SaaS landing page for freelancer proposals

All 5 agents spawn concurrently in separate tmux windows. They converse via a shared conversation.jsonl while working. Live conversation feed in your terminal. View Team Mode docs.

# Already in Claude Code? Just point it at the repo.

> Clone https://github.com/victordelrosal/octopus and set it up for me

Claude Code reads the README, runs the installer, and configures everything. You just type octopus after.

❯

The Five Agents

🟡

Researcher & Analyst

Intelligence & Evaluation

Two modes, one domain. Scout mode: market research, competitor analysis, data synthesis. Analyst mode: metrics evaluation, kill/pivot/scale recommendations. Intelligence forward and backward.

🟠

Designer

Solutions

UX/UI, system architecture, wireframes, information design. Creates solutions from research and delivers specs.

🔵

Maker

Building

Code, infrastructure, deployment, testing, CI/CD. Builds from specs, runs tests, ships working systems.

🟢

Marketer

Distribution

Copywriting, SEO, social media, ads, growth loops. Gets the product to customers with ready-to-deploy assets.

🟣

Manager

Orchestration

That's you. Plan, delegate, set quality gates, synthesize results. If you're doing the work, you're not managing.

❯

Commands

Command	What Happens
`research [topic]`	Spawn Yellow Researcher agent (Scout mode) for intelligence gathering
`evaluate [target]`	Spawn Yellow Analyst agent (Evaluate mode) for metrics and kill/pivot/scale decisions
`design [brief]`	Spawn Red-Orange Designer agent for solution architecture
`build [spec]`	Spawn Blue Maker agent to write code and ship
`market [product]`	Spawn Green Marketer agent for distribution assets
`sprint [goal]`	iFactory: Autonomous pipeline — 5 agents, 3 phases, SHIP/KILL/PIVOT decision. No human coordination. See how →
`team [tasks]`	Parallel fan-out to multiple agents simultaneously
`review [work]`	Iterative review loop between two agents
`help`	Show available agents and commands

❯

iFactory: Autonomous Sprint

Five agents. Three phases. One decision.
No human coordination required.

Type sprint [your goal] and stand back. Purple spawns Yellow + Red in parallel, feeds their outputs to Blue + Green, then synthesizes a SHIP/KILL/PIVOT decision with full VdROS governance. Human role: architect only.

Phase 1 — Parallel

● Yellow ● Red

→

Phase 2 — Parallel

● Blue ● Green

→

Phase 3 — Synthesis

● Purple

~13mproblem to decision

4agents in parallel

20+files produced

$0human hours

octopus> sprint solo founder admin overhead

Runs ifactory/launch.sh — opens 6 terminal windows, Purple orchestrates autonomously. View pipeline source →

❯

How It Works

A ──> B ──> C

Sequential

Pipeline stages. Each agent's output feeds the next. Research, then design, then build.

┌── A ──┐ M ──┼── B ──┼── M └── C ──┘

Parallel

Fan-out, fan-in. Independent tasks run simultaneously. Manager synthesizes the results.

A ──> B ──> A (repeat)

Review Loop

Iterative refinement between two agents until the quality gate passes.

M ├── Seq: R>D ├── Par: B+G └── Loop: B<>G

Full Orchestration

Combine all three. The Manager dynamically picks the right pattern per stage.

❯

Works With

💻 Claude Code

💻 Codex CLI

💻 Gemini CLI

💻 OpenCode

💻 Any LLM Terminal

❯

Operating Principles

01 Context is the bottleneck, not intelligence. Give each agent only what it needs. Less context, better performance.

02 Synthesize before delegating. The Manager must prove it understood the previous output before dispatching the next stage. No blind relays.

03 Contract before work. Define output format and success criteria before spawning any agent.

04 The Manager orchestrates; agents execute. If you're writing code, you're not managing. Delegate.

05 Fail fast, escalate early. Agents stop and ask rather than guess. No heroics.

06 Filesystem is truth. Every handoff, artifact, and state change is written to disk. No ephemeral state.

07 Ship over perfect. The goal is working output, not theoretical elegance.

❯

Changelog

2026-04-01

v1.3.0

Production-grade coordination from Claude Code's architecture. Six patterns adapted from Anthropic's leaked agent runtime (512K lines of production TypeScript). Structured completion signals: every agent now ends with a machine-parseable status block (STATUS, ARTIFACTS, SUMMARY, BLOCKERS, HANDOFF READY) so the Manager can coordinate parallel fan-outs without interpreting prose. Synthesis-before-delegation: new operating principle requiring the Manager to prove understanding of each stage's output before dispatching the next, preventing context degradation across handoffs. Risk protocol: agents can now FLAG risks mid-stage and continue with safe work, rather than the binary stop-or-continue of escalation triggers. Inherited context: spawn templates restructured with an Inherited Context section the Manager populates with mission, prior findings, constraints, and settled decisions. Cache-aware prompt ordering: templates reordered (stable identity first, volatile task last) to maximise API prompt cache hits across multi-agent runs. Tool boundary enforcement: Bash removed from Manager agent to enforce "delegate, don't do."

2026-03-04

v1.2.0

Team Mode v2: Collaborative agents. Complete rewrite of orchestrate.sh. All 5 agents now spawn concurrently (not sequentially) and converse via shared conversation.jsonl and blackboard.md. Agents with dependencies poll for prerequisites while reading early findings from upstream agents. Purple Manager monitors the conversation in real-time, resolves questions, and synthesizes. Live conversation feed in the launch terminal. New filesystem structure: .octopus/board/, .octopus/prompts/, .octopus/launch/.

2026-03-04

v1.1.0

Yellow agent expanded: Researcher & Analyst. The Researcher (Yellow) now operates in two modes: Scout mode (forward-looking market research) and Analyst mode (backward-looking evaluation with KILL / PIVOT / SCALE recommendations). New evaluate [target] command added. Quality gates updated to reflect the full six-stage pipeline: Research, Design, Build, Deploy, Distribute, Evaluate. Task Force recommendations implemented across CLAUDE.md, octopus.md, and index.html.

2026-03-03

v1.0.0

Initial release. Five-agent orchestration OS with sequential, parallel, and review loop modes. Yellow Researcher, Red-Orange Designer, Blue Maker, Green Marketer, Purple Manager. CLI installer, portable octopus.md, vision document. Platform-agnostic: works with Claude Code, Codex CLI, Gemini CLI, OpenCode, or any LLM terminal with tool use.

Start Orchestrating

Three commands to a five-agent team.

View on GitHub Read the OS Read the Vision