OpenCode MultiAgent Studio

Table of Contents

1. Overview
2. Features
3. Quick Start
4. Architecture
5. Configuration Guide
6. Plugin System
7. Skills
8. Environment Variables
9. API Reference
10. Development
11. Publishing
12. Troubleshooting
13. License

Overview

OpenCode MultiAgent Studio is a comprehensive visual configuration and orchestration tool for OpenCode's multiagent AI system. It provides a web-based wizard interface for configuring AI providers, models, agent hierarchies, and automatic failover systems.

The studio enables users to:

• Visually configure multi-agent AI workflows
• Set up automatic failover between different AI providers
• Monitor agent health in real-time
• Export portable configurations that don't store API keys

Why Use OpenCode MultiAgent Studio?

| Feature | Description | |---------|-------------| | Visual Configuration | No more editing JSON files manually - use the interactive wizard | | Automatic Failover | 4-level fallback system ensures your workflows never fail | | Portable | Configurations use environment variable references, not hardcoded keys | | Health Monitoring | Real-time dashboard shows agent status and circuit breaker states | | Flexible Providers | Support for OpenAI, Anthropic, OpenRouter, OpenCode Zen, Google, Azure |

Features

1. Visual Configuration Wizard

A 6-step interactive wizard guides users through the configuration process:

1. Welcome - Choose a preset or start from scratch
2. Providers - Select which AI providers you have API keys for
3. Default Models - Set default models for build/plan/all modes
4. Agent Models - Customize individual agent models
5. Failover - Configure automatic backup models
6. Export - Download your opencode.json configuration

2. Multiple Provider Support

The studio supports 7 major AI providers:

| Provider | Models | Environment Variable | |----------|--------|---------------------| | OpenAI | gpt-5.4, gpt-5.3-codex, gpt-4o, etc. | OPENAI_API_KEY | | Anthropic | claude-4-opus, claude-4-sonnet, claude-3.5-sonnet | ANTHROPIC_API_KEY | | OpenRouter | 40+ models via aggregation | OPENROUTER_API_KEY | | OpenCode Zen | minimax-m2.5, nemotron, qwen, etc. | OPENCODE_API_KEY | | Google | gemini-2.0-pro, gemini-1.5-pro | GOOGLE_API_KEY | | Azure OpenAI | gpt-4, gpt-35-turbo | AZURE_OPENAI_API_KEY | | Ollama | Local models | (local) |

3. Agent Hierarchy

The multiagent system consists of 3 primary agents and 19 sub-agents:

┌─────────────────────────────────────────────────────────────────┐
│                        PRIMARY AGENTS                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐    ┌──────────┐    ┌──────────┐                │
│  │  BUILD   │    │   PLAN   │    │   ALL    │                │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘                │
│       │               │               │                       │
│       ▼               ▼               ▼                       │
│  ┌─────────┐    ┌─────────┐    ┌──────────┐                │
│  │  Build  │    │  Plan   │    │  All 19  │                │
│  │ Subagents│    │Subagents│    │ agents   │                │
│  │  (13)   │    │   (6)   │    │ (parallel)│                │
│  └─────────┘    └─────────┘    └──────────┘                │
└─────────────────────────────────────────────────────────────────┘

Build Sub-agents (13)

• build-coder - Code generation
• build-tester - Test generation
• build-debugger - Error tracing and debugging
• build-refactorer - Code modernization
• build-optimizer - Performance optimization
• build-reviewer - Code review
• build-security - Security vulnerability analysis
• build-analyzer - Static code analysis
• build-documenter - Documentation generation
• build-migrator - Framework migrations
• build-explorer - Codebase exploration
• build-quick-fix - Small fixes and typos
• build-general - General implementation

Plan Sub-agents (6)

• plan-architect - Architecture and design
• plan-strategist - Strategic planning
• plan-analyzer - Requirements analysis
• plan-researcher - Deep research
• plan-reasoner - Complex logic and reasoning
• plan-reviewer - Plan validation

4. Automatic Failover System

The failover system provides 4 levels of resilience:

┌─────────────────────────────────────────────────────────────────┐
│                      FAILOVER HIERARCHY                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Level 1: RETRY                                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Exponential backoff: 1s → 2s → 4s → 8s → 16s           │   │
│  │ Max 5 retries per request                               │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  Level 2: BACKUP MODELS                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 3-4 alternative models per agent                        │   │
│  │ Priority: faster/cheaper → premium                     │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  Level 3: FALLBACK AGENT                                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Delegate to sibling agent (e.g., build-coder →        │   │
│  │ build-general)                                          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  Level 4: GRACEFUL DEGRADATION                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Return partial result with error explanation           │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

5. Health Dashboard

Real-time monitoring dashboard showing:

• Agent status (healthy/degraded/failed)
• Circuit breaker states
• Request success rates
• Response time trends
• Error rate alerts

6. Portable Plugin System

The included OpenCode plugin provides:

• Automatic failover handling
• No API key storage
• Environment variable references
• Hot-reload configuration

Quick Start

Installation

# Clone the repository
git clone https://github.com/mahmoud20138/opencode-multiagent-studio.git
cd opencode-multiagent-studio

# Install dependencies
npm install

# Start development server
npm run dev

The web UI will open at http://localhost:5173

Usage

1. Choose a Preset - Start with a pre-configured template or from scratch
2. Select Providers - Choose which AI providers you have API keys for
3. Set Default Models - Configure models for build/plan/all modes
4. Customize Agents - Optionally customize each agent's model
5. Configure Failover - Enable automatic backup models
6. Export - Download your opencode.json configuration

Architecture

Project Structure

opencode-multiagent-studio/
├── bin/                    # CLI entry point
│   └── run.js             # Executable for npm bin
├── server/                 # Express API server
│   ├── index.js           # Server entry point
│   └── routes/            # API routes
│       ├── config.js      # Configuration endpoints
│       ├── models.js      # Model catalog endpoints
│       └── health.js       # Health monitoring endpoints
├── src/                    # React frontend
│   ├── App.tsx            # Main application
│   ├── main.jsx           # React entry point
│   ├── index.css          # Global styles
│   ├── components/        # UI components
│   │   ├── wizard/        # Configuration wizard steps
│   │   │   ├── WelcomeStep.tsx
│   │   │   ├── ProvidersStep.tsx
│   │   │   ├── DefaultModelsStep.tsx
│   │   │   ├── AgentModelsStep.tsx
│   │   │   ├── FailoverStep.tsx
│   │   │   ├── ExportStep.tsx
│   │   │   └── Wizard.tsx
│   │   ├── dashboard/     # Health dashboard
│   │   │   └── Dashboard.tsx
│   │   └── layout/        # Layout components
│   │       └── Layout.tsx
│   ├── data/              # Static data catalogs
│   │   ├── providers.ts   # Provider definitions
│   │   ├── models.ts      # Model catalog (40+ models)
│   │   ├── agents.ts      # Agent definitions
│   │   └── presets.ts     # Preset configurations
│   └── types/             # TypeScript type definitions
│       └── index.ts
├── lib/                    # Multi-agent orchestration library
│   ├── orchestrator.ts     # Main orchestration logic
│   ├── scheduler.ts        # Task scheduling
│   ├── agent/             # Agent implementation
│   │   ├── agent.ts       # Base agent class
│   │   ├── pool.ts        # Agent pool management
│   │   └── runner.ts      # Agent execution
│   ├── team/              # Team collaboration
│   │   ├── team.ts        # Team management
│   │   └── messaging.ts   # Inter-agent messaging
│   ├── task/              # Task management
│   │   ├── queue.ts       # Task queue
│   │   └── task.ts        # Task definitions
│   ├── tool/              # Tool framework
│   │   ├── framework.ts   # Tool base class
│   │   ├── executor.ts    # Tool execution
│   │   └── built-in/      # Built-in tools
│   │       ├── bash.ts
│   │       ├── file-read.ts
│   │       ├── file-write.ts
│   │       ├── file-edit.ts
│   │       ├── grep.ts
│   │       └── index.ts
│   ├── llm/               # LLM adapters
│   │   ├── adapter.ts     # Base adapter
│   │   ├── openai.ts      # OpenAI adapter
│   │   ├── anthropic.ts   # Anthropic adapter
│   │   └── ollama.ts      # Ollama adapter
│   ├── memory/            # Memory management
│   │   ├── store.ts       # Memory store
│   │   └── shared.ts      # Shared memory
│   ├── utils/             # Utilities
│   │   └── semaphore.ts   # Concurrency control
│   └── types.ts           # Library types
├── opencode-plugin/        # OpenCode plugin
│   └── index.js           # Plugin entry point
├── opencode-skills/        # OpenCode skills
│   ├── multiagent-setup/
│   │   └── SKILL.md       # Setup skill
│   ├── multiagent-configure/
│   │   └── SKILL.md       # Configuration skill
│   ├── multiagent-monitor/
│   │   └── SKILL.md       # Monitoring skill
│   └── multiagent-failover/
│       └── SKILL.md       # Failover skill
├── index.html              # Vite entry point
├── index.ts                # TypeScript entry
├── vite.config.js          # Vite configuration
├── tailwind.config.js      # TailwindCSS configuration
├── postcss.config.js       # PostCSS configuration
├── tsconfig.json           # TypeScript configuration
├── package.json            # npm package configuration
└── README.md               # This file

Technology Stack

| Layer | Technology | Version | |-------|------------|---------| | Frontend | React | 18.2.0 | | Language | TypeScript | 5.6.0 | | Build Tool | Vite | 5.0.0 | | Styling | TailwindCSS | 3.3.6 | | Routing | React Router | 6.20.0 | | Backend | Express.js | 4.18.2 | | AI SDKs | OpenAI, Anthropic | Latest | | Validation | Zod | 3.23.0 | | CLI | Node.js | Latest |

Configuration Guide

Generated opencode.json

The wizard generates an opencode.json configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-5.4",
  "default_agent": "build",
  "max_parallel_agents": 5,
  "timeout": 300000,
  "agent": {
    "build": {
      "model": "openai/gpt-5.4",
      "sub_agents": ["build-coder", "build-tester", "build-debugger", ...]
    },
    "plan": {
      "model": "anthropic/claude-4-opus",
      "sub_agents": ["plan-architect", "plan-strategist", ...]
    },
    "all": {
      "model": "openai/gpt-5.4",
      "sub_agents": ["build-coder", "plan-architect", ...],
      "parallel": true
    },
    "build-coder": {
      "model": "openai/gpt-5.3-codex",
      "backup_models": [
        "anthropic/claude-4-sonnet",
        "openai/gpt-4o",
        "openrouter/anthropic/claude-3.5-sonnet"
      ],
      "fallback_agent": "build-general",
      "retry_config": {
        "max_retries": 5,
        "initial_delay": 1000,
        "max_delay": 16000,
        "backoff_multiplier": 2
      },
      "circuit_breaker": {
        "failure_threshold": 5,
        "reset_timeout": 60000
      }
    }
  }
}

Preset Configurations

The studio includes 7 preset configurations:

| Preset | Description | Use Case | |--------|-------------|----------| | Balanced | Mix of fast and accurate models | General development | | Speed | Fast models for quick iterations | Rapid prototyping | | Quality | Premium models for best results | Complex tasks | | Cost-Effective | Cheaper models for budget | Non-critical tasks | | Research | Models optimized for analysis | Research and planning | | Code Specialized | Code-focused models | Code generation | | Custom | Start from scratch | Full customization |

Plugin System

opencode-plugin/index.js

The portable plugin provides automatic failover without storing API keys:

// Plugin entry point
module.exports = {
  name: 'multiagent-failover',
  version: '1.0.0',
  
  // Agent middleware for failover
  middleware: {
    beforeAgent: async (context, next) => {
      const { agent, input } = context;
      
      // Try primary model
      try {
        return await next();
      } catch (error) {
        // Level 2: Try backup models
        for (const model of agent.backup_models || []) {
          try {
            context.model = model;
            return await next();
          } catch (e) {
            continue;
          }
        }
        
        // Level 3: Delegate to fallback agent
        if (agent.fallback_agent) {
          return await delegateTo(agent.fallback_agent, input);
        }
        
        // Level 4: Graceful degradation
        return { partial: true, error: error.message };
      }
    }
  }
};

Installation

# Copy plugin to OpenCode plugins directory
cp -r opencode-plugin ~/.opencode/plugins/multiagent-failover

Skills

OpenCode skills provide domain-specific guidance:

multiagent-setup

Initial setup and configuration guidance.

---
name: multiagent-setup
description: Initial setup guidance for OpenCode multiagent system
actions:
  - Create opencode.json
  - Configure providers
  - Set up environment variables

multiagent-configure

Modify existing configurations.

multiagent-monitor

Health monitoring and alerts.

multiagent-failover

Automatic failover handling.

Environment Variables

Required API Keys

# OpenAI (https://platform.openai.com/api-keys)
export OPENAI_API_KEY="sk-..."

# Anthropic (https://console.anthropic.com/api-key)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenRouter (https://openrouter.ai/settings)
export OPENROUTER_API_KEY="..."

# OpenCode Zen (https://opencode.ai)
export OPENCODE_API_KEY="..."

# Google AI (https://aistudio.google.com/app/apikey)
export GOOGLE_API_KEY="..."

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://YOUR_RESOURCE.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT="gpt-4"

Configuration References

In your opencode.json, use environment variable references:

{
  "model": "openai/gpt-5.4",
  "api_key": "{env:OPENAI_API_KEY}"
}

The {env:VAR} syntax references environment variables at runtime, keeping keys out of configuration files.

API Reference

Configuration Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/config | Get current configuration | | POST | /api/config | Save configuration | | GET | /api/config/export | Export as opencode.json |

Model Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/models | Get all available models | | GET | /api/models/:provider | Get models by provider |

Health Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/health | Get overall health status | | GET | /api/health/agents | Get agent statuses | | GET | /api/health/circuit-breakers | Get circuit breaker states |

Example Usage

// Fetch available models
const models = await fetch('/api/models').then(r => r.json());

// Check health
const health = await fetch('/api/health').then(r => r.json());

// Export configuration
const config = await fetch('/api/config/export').then(r => r.json());

Development

Commands

# Development
npm run dev              # Start both client and server
npm run dev:client       # Start Vite dev server only
npm run dev:server       # Start Express server only

# Build
npm run build            # Build for production
npm run preview          # Preview production build

# Production
npm start                # Start production server

# Linting
npm run lint             # Run ESLint (if configured)

Adding New Providers

1. Add provider to src/data/providers.ts:

export const providers = [
  // ... existing
  {
    id: 'new-provider',
    name: 'New Provider',
    models: ['model-1', 'model-2'],
    env_var: 'NEW_PROVIDER_API_KEY',
    docs_url: 'https://...'
  }
];

2. Add LLM adapter in lib/llm/:

// lib/llm/newprovider.ts
export class NewProviderAdapter extends LLMAdapter {
  async complete(prompt: string): Promise<string> {
    // Implementation
  }
}

Adding New Agents

1. Add agent definition in src/data/agents.ts:

export const agents = [
  // ... existing
  {
    id: 'new-agent',
    name: 'New Agent',
    description: 'What it does',
    capabilities: ['task1', 'task2'],
    parent: 'build'
  }
];

Publishing

Publishing to npm

# Login to npm
npm login

# Build the project
npm run build

# Publish
npm publish

Publishing to GitHub

# Initialize git if needed
git init
git add .
git commit -m "Initial commit"

# Create repository on GitHub and push
git remote add origin https://github.com/mahmoud20138/opencode-multiagent-studio.git
git push -u origin master

Troubleshooting

Common Issues

1. API Key Not Found

Error: API key not found for provider

Solution: Ensure the environment variable is set:

export OPENAI_API_KEY="sk-..."

2. Model Not Available

Error: Model not available in current region

Solution: Use the capacity skill to find available regions:

npx @opencode/capacity --model gpt-5.4

3. Rate Limit Errors

Error: Rate limit exceeded

Solution:

• Enable automatic failover in the wizard
• Set up backup models with different providers
• Use circuit breakers to prevent cascade failures

4. Configuration Not Loading

Error: Invalid configuration

Solution:

• Validate JSON syntax
• Ensure {env:VAR} references are valid
• Check OpenCode config schema

Debug Mode

Enable debug logging:

export DEBUG=opencode:*
npm run dev

Getting Help

• Open an issue: https://github.com/mahmoud20138/opencode-multiagent-studio/issues
• Documentation: https://opencode.ai/docs

License

MIT License - see LICENSE for details.

Changelog

v1.0.0 (2026-04-04)

• Initial release
• Visual configuration wizard (6 steps)
• Support for 7 AI providers
• 40+ models
• 19 sub-agents
• 4-level failover system
• Health dashboard
• Portable plugin system
• 4 OpenCode skills