Opencode Cli

OpenCode CLI Skill

Use OpenCode CLI for headless LLM automation via subprocess invocation.

Table of Contents

• Quick Start
• Overview
• Basic Usage
• Model Format
• Configuration
• Reference Guides
• Subprocess Invocation
• Limitations vs Claude CLI
• Environment Variables
• Verify Setup
• Best Practices

Quick Start

1. Install OpenCode CLI (see OpenCode documentation) 2. Set environment variables for the provider:

   export ANTHROPIC_API_KEY="sk-..."  # For Anthropic
   # OR
   export GOOGLE_CLOUD_PROJECT="project-id"  # For Vertex AI

3. Verify installation:

   opencode --version

4. Test with a simple prompt:

   opencode run --model google/gemini-2.5-pro "Hello, world"

Overview

OpenCode is a Go-based CLI that provides access to 75+ LLM providers through a unified interface. This skill focuses on the headless run command for automation and subprocess integration.

Basic Usage

Command Format

opencode run --model <provider/model> "<prompt>"

Key points:

• Use run subcommand for headless (non-interactive) mode
• Model format is always provider/model
• Prompt is a positional argument at the end
• No stdin support (unlike Claude CLI's -p flag)

Examples

# Using Anthropic Claude
opencode run --model anthropic/claude-sonnet-4-20250514 "Explain this code"

# Using Google Gemini
opencode run --model google/gemini-2.5-pro "Review this architecture"

# Using free Grok tier
opencode run --model opencode/grok-code "Generate tests for this function"

Model Format

Models use the pattern provider/model-name:

Configuration

Config File Locations

1. Environment variable: OPENCODE_CONFIG path 2. Project-level: opencode.json in project root 3. Global: ~/.config/opencode/opencode.json

Configs are merged (project overrides global).

Basic Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Authentication

Credentials stored in ~/.local/share/opencode/auth.json after running /connect in TUI mode, or configure via environment variables.

Reference Guides

Load the appropriate reference for detailed configuration:

Vertex AI Setup

See vertex-ai-setup.md for Vertex AI configuration including environment variables and service account setup.

Subprocess Invocation

Basic Pattern

import subprocess

result = subprocess.run(
    ["opencode", "run", "--model", "google/gemini-2.5-pro", prompt],
    capture_output=True,
    text=True,
    timeout=600
)
output = result.stdout

Key Considerations

1. Stagger parallel calls - Add 5-10 second delays between parallel invocations to avoid cache race conditions 2. Implement fallback - Consider Claude CLI as fallback if OpenCode fails 3. Health check - Use opencode --version to verify availability 4. Timeout handling - Set appropriate timeouts (default 600s for long generations)

See integration-patterns.md for complete patterns.

Limitations vs Claude CLI

Environment Variables

Verify Setup

Complete this checklist to verify a working installation:

1. Check version - Confirm CLI is installed:

   opencode --version

2. Test default model - Verify basic connectivity:

   opencode run --model google/gemini-2.5-pro "Say hello"

3. Check configuration - Review active config:

   cat ~/.config/opencode/opencode.json

4. Verify MCP servers (if configured) - Test MCP connectivity by running a command that uses MCP tools

Best Practices

1. Use project-level config - Create opencode.json for project-specific settings 2. Prefer environment variables - Use {env:VAR_NAME} syntax in config for secrets 3. Implement retries - Network failures are common; implement retry logic 4. Log output - Capture both stdout and stderr for debugging 5. Stagger parallel calls - Prevent cache race conditions with delays

OpenCode CLI Skill

A Claude Code skill for headless LLM automation using the OpenCode CLI.

Table of Contents

• Overview
• Features
• Installation
• Installing with Skilz
• Manual Installation
• Usage
• Example Prompts
• Quick Reference
• Basic Command
• Supported Providers
• Configuration Locations
• Project Structure
• Key Differences from Claude CLI
• License

Overview

This skill provides Claude with comprehensive knowledge about the OpenCode CLI, a Go-based tool that provides access to 75+ LLM providers through a unified interface. The skill focuses on the headless run command for automation and subprocess integration.

Features

• Multi-Provider Support: Access 75+ LLM providers including Anthropic, Google, OpenAI, and more
• Headless Automation: Use the run command for non-interactive LLM operations
• Subprocess Integration: Patterns for integrating OpenCode into your automation pipelines
• Local Model Support: Configuration guides for Ollama and LM Studio
• MCP Server Configuration: Set up and manage Model Context Protocol servers

Installation

Installing with Skilz

The easiest way to install this skill is using the Skilz universal installer:

# Install skilz if you haven't already
npm install -g skilz

# Install this skill
skilz install SpillwaveSolutions_opencode_cli/opencode_cli

The skill will be installed to ~/.claude/skills/opencode_cli/.

View this skill on the Skilz Marketplace.

Manual Installation

Clone or download this repository to your Claude Code skills directory:

git clone https://github.com/SpillwaveSolutions/opencode_cli.git ~/.claude/skills/opencode_cli

Or manually place the skill files in:

~/.claude/skills/opencode_cli/

Usage

The skill activates automatically when you ask Claude about:

• Configuring OpenCode CLI
• Using OpenCode for headless automation
• Setting up providers (Vertex AI, Anthropic, OpenAI, etc.)
• Configuring MCP servers
• Running local models (Ollama, LM Studio)
• Subprocess integration patterns

Example Prompts

"How do I configure opencode for Vertex AI?"
"Set up opencode with Gemini 2.5 Pro"
"What's the opencode run command syntax?"
"Configure opencode for local Ollama models"
"How do I integrate opencode into a Python subprocess?"

Quick Reference

Basic Command

opencode run --model <provider/model> "<prompt>"

Supported Providers

Configuration Locations

Configuration files are searched in the following order (project settings override global):

1. Environment Variable: OPENCODE_CONFIG path 2. Project-Level: opencode.json in project root 3. Global: ~/.config/opencode/opencode.json

Project Structure

opencode_cli/
├── SKILL.md                      # Main skill entry point
├── README.md                     # This file
└── references/
    ├── vertex-ai-setup.md        # Google Vertex AI configuration
    ├── provider-config.md        # Provider configuration guide
    ├── cloud-providers.md        # Deepseek, Kimi, Mistral, etc.
    ├── local-models.md           # Ollama, LM Studio setup
    ├── mcp-servers.md            # MCP server configuration
    └── integration-patterns.md   # Subprocess integration patterns

Key Differences from Claude CLI

License

MIT

Cloud Model Providers for OpenCode

Configure various cloud LLM providers beyond the major platforms.

Deepseek

Chinese AI lab with strong coding models.

Configuration

{
  "model": "deepseek/deepseek-coder",
  "provider": {
    "deepseek": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Deepseek",
      "options": {
        "baseURL": "https://api.deepseek.com/v1",
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      },
      "models": {
        "deepseek-coder": {
          "name": "Deepseek Coder",
          "limit": { "context": 128000, "output": 8192 }
        },
        "deepseek-chat": {
          "name": "Deepseek Chat",
          "limit": { "context": 128000, "output": 8192 }
        },
        "deepseek-reasoner": {
          "name": "Deepseek Reasoner",
          "limit": { "context": 128000, "output": 8192 }
        }
      }
    }
  }
}

Get API key: https://platform.deepseek.com/

Models

Kimi (Moonshot)

Long-context specialist from Moonshot AI.

Configuration

{
  "model": "kimi/moonshot-v1-128k",
  "provider": {
    "kimi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimi",
      "options": {
        "baseURL": "https://api.moonshot.cn/v1",
        "apiKey": "{env:MOONSHOT_API_KEY}"
      },
      "models": {
        "moonshot-v1-8k": {
          "name": "Moonshot 8K",
          "limit": { "context": 8000, "output": 4096 }
        },
        "moonshot-v1-32k": {
          "name": "Moonshot 32K",
          "limit": { "context": 32000, "output": 4096 }
        },
        "moonshot-v1-128k": {
          "name": "Moonshot 128K",
          "limit": { "context": 128000, "output": 4096 }
        },
        "kimi-k2": {
          "name": "Kimi K2",
          "limit": { "context": 200000, "output": 8192 }
        }
      }
    }
  }
}

Get API key: https://platform.moonshot.cn/

Qwen (Alibaba)

Alibaba's multilingual models.

Configuration

{
  "model": "qwen/qwen-max",
  "provider": {
    "qwen": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Qwen",
      "options": {
        "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "{env:DASHSCOPE_API_KEY}"
      },
      "models": {
        "qwen-max": {
          "name": "Qwen Max",
          "limit": { "context": 32000, "output": 8192 }
        },
        "qwen-plus": {
          "name": "Qwen Plus",
          "limit": { "context": 32000, "output": 8192 }
        },
        "qwen-turbo": {
          "name": "Qwen Turbo",
          "limit": { "context": 8000, "output": 4096 }
        },
        "qwen-coder-plus": {
          "name": "Qwen Coder Plus",
          "limit": { "context": 128000, "output": 8192 }
        }
      }
    }
  }
}

Get API key: https://dashscope.console.aliyun.com/

Mistral

European AI with efficient models.

Configuration

{
  "model": "mistral/mistral-large-latest",
  "provider": {
    "mistral": {
      "npm": "@ai-sdk/mistral",
      "options": {
        "apiKey": "{env:MISTRAL_API_KEY}"
      },
      "models": {
        "mistral-large-latest": {
          "name": "Mistral Large",
          "limit": { "context": 128000, "output": 8192 }
        },
        "mistral-medium-latest": {
          "name": "Mistral Medium",
          "limit": { "context": 32000, "output": 8192 }
        },
        "codestral-latest": {
          "name": "Codestral",
          "limit": { "context": 32000, "output": 8192 }
        },
        "devstral-latest": {
          "name": "Devstral",
          "limit": { "context": 128000, "output": 8192 }
        }
      }
    }
  }
}

Get API key: https://console.mistral.ai/

GLM (Zhipu)

Chinese multimodal models.

Configuration

{
  "model": "zhipu/glm-4",
  "provider": {
    "zhipu": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zhipu GLM",
      "options": {
        "baseURL": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "{env:ZHIPU_API_KEY}"
      },
      "models": {
        "glm-4": {
          "name": "GLM-4",
          "limit": { "context": 128000, "output": 4096 }
        },
        "glm-4-plus": {
          "name": "GLM-4 Plus",
          "limit": { "context": 128000, "output": 4096 }
        },
        "glm-4v": {
          "name": "GLM-4V (Vision)",
          "limit": { "context": 8000, "output": 4096 }
        }
      }
    }
  }
}

Get API key: https://open.bigmodel.cn/

Groq

Hardware-accelerated inference.

Configuration

{
  "model": "groq/llama-3.3-70b-versatile",
  "provider": {
    "groq": {
      "npm": "@ai-sdk/groq",
      "options": {
        "apiKey": "{env:GROQ_API_KEY}"
      },
      "models": {
        "llama-3.3-70b-versatile": {
          "name": "Llama 3.3 70B",
          "limit": { "context": 128000, "output": 32768 }
        },
        "mixtral-8x7b-32768": {
          "name": "Mixtral 8x7B",
          "limit": { "context": 32768, "output": 8192 }
        },
        "gemma2-9b-it": {
          "name": "Gemma2 9B",
          "limit": { "context": 8192, "output": 8192 }
        }
      }
    }
  }
}

Get API key: https://console.groq.com/

Together AI

Open model hosting.

Configuration

{
  "model": "together/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
  "provider": {
    "together": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Together AI",
      "options": {
        "baseURL": "https://api.together.xyz/v1",
        "apiKey": "{env:TOGETHER_API_KEY}"
      },
      "models": {
        "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo": {
          "name": "Llama 3.1 70B Turbo"
        },
        "Qwen/Qwen2.5-Coder-32B-Instruct": {
          "name": "Qwen 2.5 Coder 32B"
        },
        "deepseek-ai/DeepSeek-R1-Distill-Llama-70B": {
          "name": "DeepSeek R1 Distill"
        }
      }
    }
  }
}

Get API key: https://api.together.xyz/

Fireworks AI

Fast inference platform.

Configuration

{
  "model": "fireworks/accounts/fireworks/models/llama-v3p1-70b-instruct",
  "provider": {
    "fireworks": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Fireworks AI",
      "options": {
        "baseURL": "https://api.fireworks.ai/inference/v1",
        "apiKey": "{env:FIREWORKS_API_KEY}"
      },
      "models": {
        "accounts/fireworks/models/llama-v3p1-70b-instruct": {
          "name": "Llama 3.1 70B"
        },
        "accounts/fireworks/models/qwen2p5-coder-32b-instruct": {
          "name": "Qwen 2.5 Coder 32B"
        }
      }
    }
  }
}

Get API key: https://fireworks.ai/

Provider Comparison

Multi-Provider Setup

Combine multiple providers:

{
  "model": "deepseek/deepseek-coder",
  "small_model": "groq/gemma2-9b-it",
  "provider": {
    "deepseek": { ... },
    "groq": { ... },
    "mistral": { ... }
  }
}

Switch models easily:

opencode run --model groq/llama-3.3-70b-versatile "Fast query"
opencode run --model deepseek/deepseek-coder "Complex code task"

Integration Patterns for OpenCode CLI

Generic patterns for integrating OpenCode CLI into applications.

Note: These are documentation examples showing integration patterns.

Adapt patterns to specific subprocess handling utilities.

Command Structure

OpenCode CLI uses this command structure for headless mode:

opencode run --model <provider/model> "<prompt>"

Key components:

• run - Required subcommand for headless execution
• --model - Provider and model in provider/model format
• prompt - Positional argument (the actual prompt text)

Basic Invocation Pattern

Command Building

# Build the command as a list (safer than string concatenation)
cmd = [
    "opencode",           # CLI executable
    "run",                # Headless subcommand
    "--model", model,     # Model specification
    prompt                # Prompt as positional arg
]

Expected Behavior

Fallback Strategy

When the primary tool fails, fall back to an alternative:

Primary Tool (OpenCode)
    ↓ (on failure)
Fallback Tool (Claude CLI)
    ↓ (on failure)
Return Error

Fallback triggers: 1. Non-zero return code 2. Timeout exceeded 3. Tool not found in PATH

Important: Prevent infinite recursion by disabling fallback on the fallback call.

Parallel Execution with Stagger Delay

When running multiple OpenCode processes in parallel:

Process 0: Start immediately
Process 1: Wait 5 seconds, then start
Process 2: Wait 10 seconds, then start
Process 3: Wait 15 seconds, then start

Why stagger? OpenCode's node_modules cache can experience race conditions when multiple processes initialize simultaneously. A 5-10 second delay between starts prevents conflicts.

Stagger Calculation

delay = process_index * stagger_delay_seconds

Example with stagger_delay = 5.0 and 4 parallel processes:

• Index 0: 0s delay
• Index 1: 5s delay
• Index 2: 10s delay
• Index 3: 15s delay

Health Monitoring

Availability Check

Verify OpenCode is available before invocation:

# Check if in PATH
which opencode

# Verify version
opencode --version

Tool Selection

Check available tools and select appropriately:

if opencode available:
    use opencode
elif claude available:
    use claude
else:
    raise error

Task-Specific Routing

Route different task types to appropriate tools/models:

Configuration Pattern

[tasks.toc_generation]
cli = "claude"
model = "sonnet"

[tasks.editing]
cli = "opencode"
model = "google/gemini-2.5-pro"

[tasks.research]
cli = "claude"
model = "opus"

Error Handling

Status Categories

SUCCESS    - Completed successfully (return code 0)
TIMEOUT    - Exceeded time limit
NOT_FOUND  - CLI not in PATH
FAILED     - Non-zero return code
FALLBACK   - Primary failed, fallback succeeded

Recommended Handling

1. Capture both stdout and stderr - stderr contains error details 2. Set appropriate timeout - Default 600 seconds for long generations 3. Log duration - Track performance for optimization 4. Implement retry - Transient failures are common

Configuration Structure

Example TOML configuration for CLI routing:

[cli]
primary = "claude"        # Primary CLI tool
fallback = "opencode"     # Fallback on failure
timeout = 600             # Seconds per invocation
stagger_delay = 5.0       # Seconds between parallel starts
max_parallel_chapters = 3 # Concurrent processes

[cli.opencode]
model = "google/gemini-2.5-pro"
command = "opencode"
args = ["run"]

[cli.claude]
model = "sonnet"
command = "claude"
args = ["-p"]

Key Differences: OpenCode vs Claude CLI

Best Practices Summary

1. Always use timeouts - LLM calls can hang indefinitely 2. Implement fallback - Network issues are common 3. Stagger parallel calls - Prevents cache race conditions (5-10s delay) 4. Check availability - Verify tool exists before invocation 5. Capture stderr - Essential for debugging failures 6. Log durations - Track performance and identify slow calls 7. Route by task type - Different tasks benefit from different models 8. Use list-based commands - Safer than string concatenation

Environment Variables

Common environment variables for integration:

Local Models for OpenCode

Run LLMs locally with Ollama, LM Studio, or other local inference servers.

Ollama Setup

Installation

# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama server
ollama serve

Pull Models

# Coding models
ollama pull qwen3-coder:latest
ollama pull deepseek-coder:33b
ollama pull codellama:latest

# General models
ollama pull llama3.2:latest
ollama pull gemma3:latest
ollama pull mistral:latest

OpenCode Configuration

{
  "$schema": "https://opencode.dev/schema/opencode.json",
  "model": "ollama/qwen3-coder:latest",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:latest": {
          "name": "Qwen3 Coder"
        },
        "deepseek-coder:33b": {
          "name": "Deepseek Coder 33B"
        },
        "gemma3:latest": {
          "name": "Gemma3 Latest"
        },
        "llama3.2:latest": {
          "name": "Llama 3.2"
        }
      }
    }
  }
}

Usage

opencode run --model ollama/qwen3-coder:latest "Explain this function"

LM Studio Setup

Installation

1. Download from https://lmstudio.ai 2. Launch LM Studio 3. Download models from the UI 4. Start local server (default port: 1234)

OpenCode Configuration

{
  "model": "lmstudio/local-model",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "local-model": {
          "name": "Current LM Studio Model"
        }
      }
    }
  }
}

Recommended Local Models

For Coding

For General Tasks

Vision Models

Cloud-Routed Local Models

Some Ollama setups route to cloud models:

{
  "models": {
    "deepseek-v3.2:cloud": {
      "name": "Deepseek V3.2 Cloud"
    },
    "kimi-k2:1t-cloud": {
      "name": "Kimi K2 1T Cloud"
    },
    "gemini-3-flash-preview:cloud": {
      "name": "Gemini 3 Flash Cloud"
    }
  }
}

These use local Ollama as proxy to cloud APIs.

Hardware Requirements

Minimum (7B models)

• 16GB RAM
• 8GB VRAM (GPU optional)

Recommended (13-34B models)

• 32GB RAM
• 16GB+ VRAM
• Apple Silicon M2+ or RTX 3090+

Optimal (70B+ models)

• 64GB+ RAM
• 24GB+ VRAM (A100, H100)

Performance Tips

GPU Acceleration

# Check GPU availability
ollama ps

# Force GPU layers
OLLAMA_NUM_GPU=999 ollama serve

Context Size

Large contexts require more memory:

# Increase context (default: 2048)
ollama run qwen3-coder --ctx-size 8192

Concurrent Requests

# Set max concurrent requests
OLLAMA_MAX_LOADED_MODELS=2 ollama serve

Troubleshooting

Model Not Loading

# Check Ollama status
ollama list

# Re-pull model
ollama pull model-name

Out of Memory

• Use smaller quantization (q4 vs q8)
• Reduce context size
• Close other applications

Slow Response

• Enable GPU acceleration
• Use smaller model
• Check available VRAM

Connection Refused

# Verify server is running
curl http://localhost:11434/v1/models

# Restart Ollama
ollama serve

Quantization Levels

Select quantization when pulling:

ollama pull qwen3-coder:latest-q4

MCP Server Configuration for OpenCode

Configure Model Context Protocol (MCP) servers to extend OpenCode with additional tools.

Configuration Location

Add MCP servers in opencode.json:

{
  "$schema": "https://opencode.dev/schema/opencode.json",
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["npx", "-y", "@package/name"],
      "enabled": true,
      "environment": {}
    }
  }
}

Common MCP Servers

Brave Search

Web search capability:

{
  "mcp": {
    "brave-search": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
      "enabled": true,
      "environment": {
        "BRAVE_API_KEY": "{env:BRAVE_API_KEY}"
      }
    }
  }
}

Get API key: https://brave.com/search/api/

Context7 (Documentation Lookup)

Library documentation access:

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"],
      "enabled": true
    }
  }
}

No API key required.

Perplexity Ask

AI-powered search:

{
  "mcp": {
    "perplexity-ask": {
      "type": "local",
      "command": ["npx", "-y", "server-perplexity-ask"],
      "enabled": true,
      "environment": {
        "PERPLEXITY_API_KEY": "{env:PERPLEXITY_API_KEY}"
      }
    }
  }
}

Get API key: https://www.perplexity.ai/settings/api

Notion API

Notion workspace access:

{
  "mcp": {
    "notionApi": {
      "type": "local",
      "command": ["npx", "-y", "@notionhq/notion-mcp-server"],
      "enabled": true,
      "environment": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer {env:NOTION_API_KEY}\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}

Get API key: https://www.notion.so/my-integrations

GitHub

Repository access:

{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "enabled": true,
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

Filesystem

Local file access:

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": [
        "npx", "-y", "@anthropic-ai/mcp-server-filesystem",
        "/path/to/allowed/directory"
      ],
      "enabled": true
    }
  }
}

Sequential Thinking

Chain-of-thought reasoning:

{
  "mcp": {
    "sequential-thinking": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic-ai/mcp-server-sequential-thinking"],
      "enabled": true
    }
  }
}

Memory

Persistent memory across sessions:

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic-ai/mcp-server-memory"],
      "enabled": true
    }
  }
}

Configuration Options

Server Types

Common Fields

{
  "server-name": {
    "type": "local",
    "command": ["executable", "arg1", "arg2"],
    "enabled": true,
    "environment": {
      "VAR_NAME": "value"
    }
  }
}

Environment Variables

Use variable substitution for secrets:

{
  "environment": {
    "API_KEY": "{env:MY_API_KEY}"
  }
}

Best practice: Never commit API keys. Use environment variables.

Multiple Servers Example

{
  "$schema": "https://opencode.dev/schema/opencode.json",
  "mcp": {
    "brave-search": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
      "enabled": true,
      "environment": {
        "BRAVE_API_KEY": "{env:BRAVE_API_KEY}"
      }
    },
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"],
      "enabled": true
    },
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "enabled": true,
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

Disabling Servers

Set enabled: false to disable without removing:

{
  "mcp": {
    "expensive-server": {
      "type": "local",
      "command": ["..."],
      "enabled": false
    }
  }
}

Troubleshooting

Server Not Loading

1. Check npx is available 2. Verify package name is correct 3. Check environment variables are set 4. Look at OpenCode logs for errors

Permission Errors

Ensure environment variables are accessible:

# Verify variable is set
echo $BRAVE_API_KEY

Package Not Found

Update npm cache:

npx -y clear-npx-cache
npx -y @package/name

Provider Configuration for OpenCode

Configure multiple LLM providers with OpenCode CLI.

Configuration File Format

OpenCode uses JSON/JSONC format with schema validation:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider/model-name",
  "small_model": "provider/cheaper-model",
  "provider": {
    "provider-name": {
      "npm": "@ai-sdk/package-name",
      "name": "Display Name",
      "options": {},
      "models": {}
    }
  }
}

File Locations

Configs are merged in precedence order:

1. OPENCODE_CONFIG environment variable (highest) 2. opencode.json in project root 3. ~/.config/opencode/opencode.json (lowest)

Built-in Providers

Anthropic

{
  "model": "anthropic/claude-sonnet-4-20250514",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Environment: ANTHROPIC_API_KEY

OpenAI

{
  "model": "openai/gpt-4o",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Environment: OPENAI_API_KEY

Google AI (Direct)

{
  "model": "google/gemini-2.5-pro",
  "provider": {
    "google": {
      "options": {
        "apiKey": "{env:GOOGLE_GENERATIVE_AI_API_KEY}"
      }
    }
  }
}

Environment: GOOGLE_GENERATIVE_AI_API_KEY

OpenCode Free Tier

No configuration needed - use directly:

opencode run --model opencode/grok-code "Your prompt"

Custom Provider Setup

OpenAI-Compatible APIs

For providers with OpenAI-compatible endpoints:

{
  "model": "custom/my-model",
  "provider": {
    "custom": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Custom Provider",
      "options": {
        "baseURL": "https://api.custom-provider.com/v1",
        "apiKey": "{env:CUSTOM_API_KEY}",
        "headers": {
          "X-Custom-Header": "value"
        }
      },
      "models": {
        "my-model": {
          "name": "My Custom Model",
          "limit": {
            "context": 128000,
            "output": 4096
          }
        }
      }
    }
  }
}

Local Models (Ollama)

{
  "model": "ollama/llama3.2",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama3.2": {
          "name": "Llama 3.2 (local)"
        },
        "codellama": {
          "name": "Code Llama (local)"
        }
      }
    }
  }
}

LM Studio

{
  "model": "lmstudio/local-model",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "local-model": {
          "name": "Local Model"
        }
      }
    }
  }
}

Provider Control

Disable Specific Providers

Prevent providers from loading even with valid credentials:

{
  "disabled_providers": ["openai", "google"]
}

Allowlist Providers

Only allow specific providers:

{
  "enabled_providers": ["anthropic", "google-vertex"]
}

Note: disabled_providers takes priority over enabled_providers.

Variable Substitution

Environment Variables

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

File References

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Supports:

• Absolute paths: /path/to/file
• Home directory: ~/path/to/file
• Relative paths: ./path/to/file (relative to config directory)

Model Configuration

Token Limits

Specify context window and output limits:

{
  "models": {
    "my-model": {
      "name": "Display Name",
      "limit": {
        "context": 200000,
        "output": 8192
      }
    }
  }
}

Small Model

Configure a cheaper model for lightweight tasks:

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

OpenCode automatically uses small_model for tasks like title generation.

Authentication Methods

API Key (Most Common)

{
  "options": {
    "apiKey": "{env:API_KEY}"
  }
}

AWS Bedrock

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

Azure OpenAI

{
  "provider": {
    "azure": {
      "npm": "@ai-sdk/azure",
      "options": {
        "resourceName": "{env:AZURE_RESOURCE_NAME}",
        "apiKey": "{env:AZURE_API_KEY}"
      }
    }
  }
}

Google Cloud (ADC)

Use Application Default Credentials:

gcloud auth application-default login

Or service account:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Complete Example

Multi-provider configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "google/gemini-2.5-flash",

  "disabled_providers": ["openai"],

  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "google": {
      "options": {
        "apiKey": "{env:GOOGLE_GENERATIVE_AI_API_KEY}"
      }
    },
    "google-vertex": {
      "npm": "@ai-sdk/google-vertex",
      "options": {
        "project": "{env:GOOGLE_CLOUD_PROJECT}",
        "location": "us-central1"
      },
      "models": {
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro (Vertex)"
        }
      }
    },
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama Local",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama3.2": { "name": "Llama 3.2" },
        "codellama": { "name": "Code Llama" }
      }
    }
  }
}

Verification

List available models after configuration:

# In TUI mode
opencode
# Then type /models

# Or test headless
opencode run --model provider/model "Test prompt"

Vertex AI Setup for OpenCode

Configure OpenCode to use Google Cloud Vertex AI for access to Gemini and Claude models.

Prerequisites

1. Google Cloud project with Vertex AI API enabled 2. Service account with Vertex AI User role (or equivalent) 3. Service account JSON key file 4. OpenCode CLI installed

Environment Variables

Set these before running OpenCode:

# Required
export GOOGLE_CLOUD_PROJECT="your-project-id"

# Authentication (choose one)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
# OR use gcloud CLI authentication:
# gcloud auth application-default login

# Optional - defaults to 'global'
export VERTEX_LOCATION="us-central1"

Tip: Use global for the location to improve availability without extra cost.

Configuration File

Basic Vertex AI Setup

Create ~/.config/opencode/opencode.json or project-level opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "google-vertex/gemini-2.5-pro",
  "provider": {
    "google-vertex": {
      "npm": "@ai-sdk/google-vertex",
      "options": {
        "project": "{env:GOOGLE_CLOUD_PROJECT}",
        "location": "{env:VERTEX_LOCATION}"
      },
      "models": {
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro",
          "limit": {
            "context": 1000000,
            "output": 65536
          }
        },
        "gemini-2.5-flash": {
          "name": "Gemini 2.5 Flash",
          "limit": {
            "context": 1000000,
            "output": 65536
          }
        }
      }
    }
  }
}

Claude on Vertex AI

Claude models on Vertex AI require a different SDK package:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "vertex-anthropic/claude-sonnet-4",
  "provider": {
    "vertex-anthropic": {
      "npm": "@ai-sdk/google-vertex/anthropic",
      "options": {
        "project": "{env:GOOGLE_CLOUD_PROJECT}",
        "location": "us-east5"
      },
      "models": {
        "claude-sonnet-4": {
          "name": "Claude Sonnet 4 (Vertex)",
          "limit": {
            "context": 200000,
            "output": 8192
          }
        },
        "claude-opus-4": {
          "name": "Claude Opus 4 (Vertex)",
          "limit": {
            "context": 200000,
            "output": 8192
          }
        }
      }
    }
  }
}

Important: Claude on Vertex is only available in specific regions (us-east5, europe-west1).

Service Account Setup

Create Service Account

# Create service account
gcloud iam service-accounts create opencode-vertex \
    --display-name="OpenCode Vertex AI Access"

# Grant Vertex AI User role
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:opencode-vertex@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

# Create and download key
gcloud iam service-accounts keys create ~/opencode-vertex-key.json \
    --iam-account=opencode-vertex@YOUR_PROJECT_ID.iam.gserviceaccount.com

Set Credentials

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/opencode-vertex-key.json"

Using Variable Substitution

OpenCode supports environment variable substitution in config:

{
  "provider": {
    "google-vertex": {
      "options": {
        "project": "{env:GOOGLE_CLOUD_PROJECT}",
        "location": "{env:VERTEX_LOCATION}"
      }
    }
  }
}

Also supports file references:

{
  "provider": {
    "google-vertex": {
      "options": {
        "credentials": "{file:~/.secrets/vertex-credentials.json}"
      }
    }
  }
}

Available Vertex AI Models

Gemini Models

Claude Models (via Vertex)

Verification

Test the configuration:

# Set environment
export GOOGLE_CLOUD_PROJECT="your-project"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

# Test with a simple prompt
opencode run --model google-vertex/gemini-2.5-flash "Hello, respond with OK"

Troubleshooting

Authentication Errors

Error: Could not load the default credentials

Fix: Ensure GOOGLE_APPLICATION_CREDENTIALS points to valid service account JSON, or run gcloud auth application-default login.

Permission Denied

Error: Permission 'aiplatform.endpoints.predict' denied

Fix: Grant the service account the roles/aiplatform.user role.

Region Not Available

Error: Model not available in region

Fix: Claude models are only in specific regions. Use us-east5 or europe-west1 for Claude. Gemini is available in most regions.

Model Not Found

Error: Model 'xyz' not found

Fix: Verify the model ID matches Vertex AI naming. Use the /models command in OpenCode TUI to see available models.

Cost Considerations

• Vertex AI pricing differs from direct API access
• Consider using gemini-2.5-flash for cost-sensitive operations
• Claude on Vertex may have different pricing than direct Anthropic API
• Use small_model config option for lightweight tasks