Opencode Doc

OpenCode Documentation Skill

This skill provides comprehensive documentation for OpenCode, an open-source AI coding agent available as a terminal interface, desktop app, or IDE extension.

Quick Reference

Installation

# Install script (recommended)
curl -fsSL https://opencode.ai/install | bash

# Node.js
npm install -g opencode-ai

# Homebrew (macOS/Linux)
brew install anomalyco/tap/opencode

# Windows (Chocolatey)
choco install opencode

# Windows (Scoop)
scoop install opencode

# Docker
docker run -it --rm ghcr.io/anomalyco/opencode

First Run

cd /path/to/project
opencode
/init  # Initialize project with AGENTS.md

Key Commands

Configuration

Config Locations (Precedence Order)

1. Remote config (.well-known/opencode) - organizational defaults
2. Global config (~/.config/opencode/opencode.json) - user preferences
3. Custom config (OPENCODE_CONFIG env var)
4. Project config (opencode.json in project root)
5. .opencode directories - agents, commands, plugins
6. Inline config (OPENCODE_CONFIG_CONTENT env var)

Config File Format

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "share": "manual",
  "default_agent": "code"
}

Variable Substitution

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Providers

OpenCode supports 75+ LLM providers via AI SDK and Models.dev.

Supported Providers

• OpenCode Zen - Curated models tested by OpenCode team
• Anthropic - Claude Pro/Max
• OpenAI - ChatGPT Plus/Pro
• Amazon Bedrock
• Azure OpenAI
• GitHub Copilot
• Google Vertex AI
• Groq
• OpenRouter
• DeepSeek
• Local Models - Ollama, LM Studio, llama.cpp

Configure Provider

/connect  # In TUI, select provider

Credentials stored in: ~/.local/share/opencode/auth.json

Custom OpenAI-Compatible Provider

{
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Provider",
      "options": {
        "baseURL": "https://api.myprovider.com/v1"
      },
      "models": {
        "my-model": {
          "name": "My Model"
        }
      }
    }
  }
}

Local Models (Ollama)

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

Tools

Built-in Tools

Tool Permissions

{
  "permission": {
    "edit": "ask",      // Require approval
    "bash": "allow",    // Auto-approve
    "webfetch": "deny", // Block tool
    "mymcp_*": "ask"    // Wildcard pattern
  }
}

Permission values: "allow", "deny", "ask"

MCP Servers

Add external tools via Model Context Protocol.

Local MCP Server

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-package"],
      "enabled": true,
      "environment": {
        "MY_VAR": "value"
      }
    }
  }
}

Remote MCP Server

{
  "mcp": {
    "my-remote": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer {env:API_KEY}"
      }
    }
  }
}

OAuth Authentication

opencode mcp auth my-server     # Authenticate
opencode mcp list               # List servers
opencode mcp logout my-server   # Remove credentials

Popular MCP Servers

Sentry:

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Context7:

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Grep by Vercel:

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Per-Agent MCP

{
  "mcp": { "my-mcp": { ... } },
  "tools": { "my-mcp*": false },
  "agent": {
    "my-agent": {
      "tools": { "my-mcp*": true }
    }
  }
}

Agents

Configure Custom Agent

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer...",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Agent Files

Create .opencode/agents/<name>/AGENT.md:

---
name: my-agent
description: My custom agent
model: anthropic/claude-sonnet-4-5
tools:
  bash: true
  edit: true
---

## Instructions

Your custom agent instructions here.

Built-in Agents

• code - Default coding agent
• plan - Planning mode (no modifications)
• Task agents (subagents)

Skills

Reusable instruction sets loaded on-demand.

Skill Locations

• Project: .opencode/skills/<name>/SKILL.md
• Global: ~/.config/opencode/skills/<name>/SKILL.md
• Claude-compatible: .claude/skills/<name>/SKILL.md

Create a Skill

---
name: my-skill
description: Brief description (1-1024 chars)
license: MIT
compatibility: opencode
metadata:
  key: value
---

## Instructions

Your skill content here.

Skill Name Rules

• 1-64 characters
• Lowercase alphanumeric with single hyphens
• Must match directory name
• Regex: ^[a-z0-9]+(-[a-z0-9]+)*$

Skill Permissions

{
  "permission": {
    "skill": {
      "*": "allow",
      "internal-*": "deny"
    }
  }
}

Commands

Custom slash commands in .opencode/commands/.

Create Command

.opencode/commands/my-command.md:

---
name: my-command
description: My custom command
---

Execute this task: $ARGUMENTS

Command Variables

• $ARGUMENTS - User-provided arguments
• $SELECTION - Selected text/code
• $FILE - Current file path

Keybinds

{
  "keybinds": {
    "input:submit": ["enter", "ctrl+enter"],
    "input:newline": ["shift+enter"],
    "session:new": ["ctrl+n"],
    "session:list": ["ctrl+l"],
    "mode:toggle": ["tab"],
    "quit": ["ctrl+c", "ctrl+d"]
  }
}

Themes

{
  "theme": "tokyonight"
}

Built-in themes: opencode, tokyonight, catppuccin, gruvbox, nord, dracula

Custom themes in ~/.config/opencode/themes/.

Formatters

Auto-format code after edits:

{
  "formatter": {
    "*.ts": "prettier --write",
    "*.go": "gofmt -w",
    "*.py": "black"
  }
}

CLI Commands

opencode                    # Start TUI
opencode run "prompt"       # Non-interactive
opencode run -p prompt.md   # From file
opencode serve              # Start server
opencode web                # Web interface
opencode auth list          # List credentials
opencode mcp list           # List MCP servers
opencode mcp auth <name>    # Authenticate MCP

SDK

import { createSession } from "opencode-ai/sdk"

const session = await createSession({
  model: "anthropic/claude-sonnet-4-5"
})

for await (const event of session.chat("Hello")) {
  console.log(event)
}

Plugins

{
  "plugin": ["opencode-helicone-session", "@my-org/plugin"]
}

Create plugins with hooks for session.create, session.chat, tool.call.

File Reference

All documentation files available in this skill directory:

For detailed information on any topic, read the corresponding markdown file in this skill directory.