opencode-matrix-agents 🧬

Dynamic Model + Role Matrix Subagents for OpenCode V2
Multiply your Markdown agents across your favorite LLM models on demand without duplicating files or cluttering your primary agent selector.

---

💡 The Problem

You want to:

• Use specific models (e.g. GPT-Sol, Grok, Gemini Flash, Claude Haiku) for specific subagent tasks.
• Keep reusable instructions in Markdown (e.g. cloud-ops.md, reviewer.md, researcher.md).
• Tag them cleanly via @mention (e.g. @sol/cloud-ops, @flash/reviewer, @grok/planner).
• Avoid file duplication (no need to maintain sol-reviewer.md, grok-reviewer.md, flash-reviewer.md, etc.).
• Avoid UI clutter in the main session switcher (your dropdown stays clean with only your primary base agents).

---

⚡ How It Works

1. You write your standard base agents in Markdown once (e.g., cloud-ops.md with mode: all or mode: primary).
2. You define your preferred workhorse model aliases in opencode.json.
3. At startup, this plugin registers:
   • Standalone model workers: @sol, @grok, @flash, @haiku
   • Role combinations: @sol/cloud-ops, @flash/reviewer, @grok/planner
4. All matrix combinations are created with mode: "subagent".
   • Main Agent Picker: Only shows your clean base agents (build, cloud-ops, planner).
   • @ Mentions & Subagent Delegations: All @<model>/<role> combinations are available!

---

📦 Installation

Option 1: Direct Local / Global Plugin

Copy or link the plugin file into your global OpenCode plugins folder:

mkdir -p ~/.config/opencode/plugins
cp dist/index.js ~/.config/opencode/plugins/matrix-agents.js

Option 2: Configured in opencode.json

Add the plugin path and your model mappings to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    {
      "package": "/path/to/opencode-matrix-agents/dist/index.js",
      "options": {
        "models": {
          "grok": "xai/grok-2",
          "sol": "openai/gpt-5-sol",
          "flash": "google/gemini-2.0-flash",
          "haiku": "anthropic/claude-3-5-haiku",
          "sonnet": "anthropic/claude-3-7-sonnet"
        },
        "roles": ["cloud-ops", "reviewer", "researcher", "planner"],
        "colors": {
          "sol": "#10A37F",
          "flash": "#4285F4",
          "grok": "#FF6F00",
          "haiku": "#D97706"
        }
      }
    }
  ]
}

---

📝 Example: Defining a Base Agent

Create .opencode/agents/cloud-ops.md (or ~/.config/opencode/agents/cloud-ops.md):

---
description: Google Cloud & Kubernetes specialist for cluster deployments, pods, and logs.
mode: all
color: "#4285F4"
permissions:
  - action: shell
    resource: "kubectl delete *"
    effect: ask
  - action: shell
    resource: "gcloud * delete *"
    effect: ask
---

You are an expert Google Cloud & Kubernetes Infrastructure Engineer.

### Guidelines:
1. Always verify the active context: `kubectl config current-context` and `gcloud config get-value project`.
2. Inspect pod health, deployments, and logs before taking action.
3. Ask for confirmation before executing any destructive operations.

---

🚀 Usage Examples

1. Tagging in Chat

@flash/cloud-ops check why the payment-service pod is in CrashLoopBackOff.

@sol/reviewer perform a deep security & race condition audit on src/auth.ts.

@haiku/researcher scan the repo and list all deprecated API usages.

2. Autonomous Main Agent Delegation

You can ask your primary agent:

"Launch two subagents in parallel in the background:
- @grok/planner to evaluate database concurrency trade-offs.
- @sol/cloud-ops to draft the Terraform deployment manifest.
Meanwhile, let's keep working on the API endpoints here."

3. Having a Direct 1-on-1 Conversation

Because cloud-ops.md was created with mode: all, you can simply select cloud-ops in the OpenCode agent picker and converse directly with it using whatever model you have currently selected.

---

⚙️ Configuration Options

Option	Type	Default	Description
models	Record<string, string>	{}	Map of alias to provider/modelID.
roles	string[]	undefined	Optional whitelist of base agent IDs to multiply. If omitted, all top-level Markdown agents are multiplied.
skipAgents	string[]	[]	Additional agent IDs to exclude from matrix generation.
workers	boolean	true	When true, registers standalone subagent aliases (e.g. @sol, @grok).
subagentOnly	boolean	true	When true, all generated matrix combinations are restricted to mode: "subagent" to keep the primary agent switcher clean.
colors	Record<string, string>	{}	Map of model alias to UI hex color code.

---

🛠️ Development

# Run tests
bun test

# Build TypeScript
bun run build

---

📄 License

MIT © Luis Moreno