🚀 Boomerang for OpenCode

Intelligent multi-agent coordination for OpenCode — because great software is a team sport.

🚀 Vanilla OpenCode Install (One-Click Prompt)

Copy and paste the following prompt into a fresh OpenCode Builder session. It will do everything automatically.

I want you to install the Boomerang multi-agent plugin for OpenCode. Do this step by step:

1. Install the Boomerang package from PyPI. Run: pip install opencode-boomerang (or uv tool install opencode-boomerang if uv is available).

2. Install super-memory from PyPI. Run: pip install super-memory (or uv tool install super-memory if uv is available).

3. Edit the project's .opencode/opencode.json file to include:
   - The Boomerang plugin: "plugin": ["opencode-boomerang"]
   - An MCP server entry for super-memory with command ["super-memory"] or ["uv", "run", "super-memory"] depending on how it was installed
   - An MCP server entry for sequential-thinking with command ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]

4. Confirm completion and tell me to:
   a) Restart OpenCode completely
   b) After restart, open the Skills panel (type /skills) and select "boomerang-init" to run the initialization skill

🎯 What is Boomerang?

Boomerang is an intelligent multi-agent orchestration plugin for OpenCode that coordinates a team of specialized AI agents working together on your codebase. Instead of relying on a single AI, Boomerang implements the Boomerang Protocol — a structured 6-step workflow that ensures thorough, consistent, and high-quality code delivery.

Think of it as your AI development team lead — the Orchestrator plans the work, delegates to specialists, enforces quality gates, and ensures nothing falls through the cracks.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          USER                                    │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              🎯 ORCHESTRATOR (Kimi K2.5)                         │
│   • Plans task execution & dependency graph                       │
│   • Delegates to specialized sub-agents                          │
│   • Enforces quality gates                                       │
└────────────────────────────┬────────────────────────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   💻        │      │   🏗️        │      │   🔍        │
│  CODER      │      │ ARCHITECT  │      │ EXPLORER   │
│ MiniMax M2.7│      │ Kimi K2.5  │      │ MiniMax M2.7│
└─────────────┘      └─────────────┘      └─────────────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                  🔄 THE BOOMERANG PROTOCOL                       │
│                                                                 │
│   1️⃣ Memory   →   2️⃣ Think   →   3️⃣ Delegate                  │
│   4️⃣ Git Check →   5️⃣ Quality Gates →   6️⃣ Save Memory        │
└─────────────────────────────────────────────────────────────────┘

The 6-Step Boomerang Protocol

🤖 Agent Roster

🧠 Super-Memory Integration

⚠️ SUPER-MEMORY IS REQUIRED — Boomerang will not function without it.

Why is super-memory required?

Unlike simple context windows, super-memory provides persistent long-term memory across sessions. When you start a new OpenCode session, Boomerang agents automatically:

• Query memory at start — Retrieve relevant context, past decisions, and learnings from previous sessions
• Save memory at end — Persist key decisions, code patterns, and project-specific knowledge

This means Boomerang learns your codebase over time and doesn't repeat mistakes.

Installation

# Using uv (recommended)
uv tool install super-memory

# Or using pip
pip install super-memory

Configuration

Add super-memory to your global ~/.opencode/opencode.json:

{
  "mcp": {
    "super-memory": {
      "type": "local",
      "command": ["super-memory"],
      "enabled": true
    }
  }
}

Note: If you installed with uv run, use "command": ["uv", "run", "super-memory"]

Verify Installation

super-memory --version

📋 Prerequisites

🚚 Installation

⭐ For the easiest install experience, use the "Vanilla OpenCode Install" prompt above — just copy, paste, and let OpenCode do everything!

Option 2: Manual Install

1. Install Boomerang from PyPI:

   pip install opencode-boomerang
   # Or if using uv
   uv tool install opencode-boomerang
   

2. Install super-memory from PyPI:

   pip install super-memory
   # Or if using uv
   uv tool install super-memory
   

3. Update your .opencode/opencode.json to include the plugin:

   {
     "plugin": ["opencode-boomerang"]
   }
   

4. Add super-memory and sequential-thinking MCP configurations (see Configuration section below)
5. Start OpenCode and run /boomerang-init skill
6. Restart OpenCode for agents to load

⚙️ Configuration

Example opencode.json

{
  "plugin": ["opencode-boomerang"],
  "mcp": {
    "super-memory": {
      "type": "local",
      "command": ["super-memory"],
      "enabled": true
    },
    "searxng": {
      "type": "local",
      "command": ["npx", "-y", "mcp-searxng"],
      "environment": { "SEARXNG_URL": "http://localhost:8080" },
      "enabled": false
    },
    "sequential-thinking": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"],
      "enabled": true
    }
  }
}

Key Configuration Points

🔄 The Boomerang Protocol (Detailed)

Every Boomerang session follows this strict protocol:

Step 1: Memory Query

At session start, agents query super-memory for:
• Previous decisions and rationale
• Project-specific patterns and conventions
• Known issues and workarounds
• User preferences and habits

Step 2: Think & Plan

The Orchestrator:
• Breaks down the task into subtasks
• Identifies dependencies between subtasks
• Builds an execution DAG (Directed Acyclic Graph)
• Determines which agents to delegate to

Step 3: Delegate

Sub-agents are invoked based on specialty:
• Code generation → boomerang-coder
• Design review → boomerang-architect
• Exploration → boomerang-explorer
• Testing → boomerang-tester
• Quality → boomerang-linter
• Version control → boomerang-git

Step 4: Git Check

Before any work is considered complete:
• git status shows clean working tree (or changes staged)
• Commits are made with descriptive messages
• Branches are properly managed

Step 5: Quality Gates

Mandatory checks before completion:
✓ Lint passes (boomerang-linter)
✓ Typecheck passes (where applicable)
✓ Tests pass (boomerang-tester)
✓ No regression in existing functionality

Step 6: Save Memory

At session end, critical information is saved:
• Key architectural decisions
• Code patterns established
• Lessons learned
• User preferences

🔥 Release Pipeline & Updating

When a new version of Boomerang is released:

1. Check for Updates

gh release view Veedubin/opencode-boomerang --json tagName,createdAt

2. Update Your Installation

# Update Boomerang from PyPI
pip install --upgrade opencode-boomerang
# Or if using uv
uv tool upgrade opencode-boomerang

# Re-run initialization
opencode /boomerang-init

3. Verify Installation

# Check the version in your installed plugin
cat .opencode/plugins/boomerang/package.json | grep version

📁 Release Package Contents

The boomerang.tar.gz release contains:

.opencode/
├── agents/                    # Agent definitions
│   ├── boomerang.md          # Orchestrator
│   ├── boomerang-coder.md    # Code generation
│   ├── boomerang-architect.md # Architecture
│   ├── boomerang-explorer.md  # Exploration
│   ├── boomerang-tester.md    # Testing
│   ├── boomerang-linter.md    # Linting
│   ├── boomerang-git.md       # Git operations
│   └── researcher.md          # Web research
├── skills/                    # Boomerang skills
│   ├── boomerang-architect/
│   ├── boomerang-coder/
│   ├── boomerang-init/
│   ├── boomerang-orchestrator/
│   └── boomerang-tester/
└── plugins/boomerang/        # Plugin implementation
    ├── dist/                  # Compiled JavaScript
    └── package.json

📄 License

MIT License — see LICENSE for details.