Opencode

You are an expert in OpenCode (v1.1.31+), the AI coding CLI that provides a TUI, headless server, web interface, and desktop app for AI-assisted development. OpenCode is feature-comparable to Claude Code but with multi-provider support, custom agents, and a server architecture.

Core Mental Model

• OpenCode = AI coding agent + multi-provider + server architecture -- one tool gives you TUI, headless server, web UI, and desktop app
• Sessions are the unit of work -- each session has messages, tool calls, file diffs, and can be exported/imported/shared
• Agents define behavior -- built-in (build, plan, explore, general) or custom (.opencode/agent/*.md)
• Providers are pluggable -- Anthropic, OpenAI, Google, AWS Bedrock, Azure, xAI, Mistral, Groq, OpenRouter, etc.
• MCP servers extend capabilities -- local (stdio) or remote (HTTP/SSE) with OAuth support
• Skills provide domain expertise -- .opencode/skill/**/SKILL.md or .claude/skills/**/SKILL.md (compat mode)
• Commands are reusable prompts -- .opencode/command/*.md with dynamic shell interpolation
• Plugins extend hooks and tools -- TypeScript/JavaScript modules via .opencode/plugin/

Architecture

~/.config/opencode/           # Global config
  opencode.json[c]            # Global settings
~/.local/share/opencode/      # Data (sessions, storage)
  session/{projectID}/        # Session files
  message/{sessionID}/        # Message files
  part/{messageID}/           # Message parts (text, tool calls)
  session_diff/{sessionID}/   # File diffs per session
~/.cache/opencode/            # Cache
~/.local/state/opencode/      # State

project/                      # Project root
  opencode.json[c]            # Project config (searched up tree)
  .opencode/
    agent/*.md                # Custom agents (YAML frontmatter + prompt)
    command/*.md              # Custom commands (with shell interpolation)
    skill/**/SKILL.md         # Custom skills
    tool/*.{ts,js}            # Custom tools (TypeScript/JS)
    plugin/                   # Local plugins
    themes/*.json             # Custom TUI themes
    plans/*.md                # Plan mode files (VCS-backed)

CLI Reference

Primary Commands

opencode run -- Non-Interactive Mode

opencode run "fix the login bug"                    # single message
opencode run -c                                      # continue last session
opencode run -s <session-id>                         # continue specific session
opencode run -m anthropic/claude-sonnet-4-20250514      # specify model
opencode run --agent plan                            # use plan agent
opencode run --format json                           # JSON output
opencode run -f screenshot.png "what's wrong here?"  # attach file
opencode run --title "Auth Fix"                      # set session title
opencode run --variant high                          # reasoning effort variant
opencode run --prompt-file instructions.md           # prompt from file
opencode run --attach --port 3000                    # attach to running server

opencode serve -- Headless Server

opencode serve                                       # default port
opencode serve --port 3000                           # custom port
opencode serve --hostname 0.0.0.0                    # bind all interfaces
opencode serve --mdns                                # enable mDNS discovery
opencode serve --cors "https://example.com"          # CORS whitelist

Requires OPENCODE_SERVER_PASSWORD for basic auth.

Authentication

Agent Management

MCP Server Management

Session Management

Model Management

GitHub Integration

Statistics

Debugging

Maintenance

ACP (Agent Client Protocol)

Global Flags

Configuration System

Config File Hierarchy (Low to High Precedence)

1. Remote well-known: ${AUTH_URL}/.well-known/opencode
2. Global: ~/.config/opencode/opencode.json[c]
3. Custom path: OPENCODE_CONFIG env var
4. Project: opencode.json[c] (searched up directory tree)
5. Inline: OPENCODE_CONFIG_CONTENT env var (highest)

Config Schema

{
  "$schema": "https://opencode.ai/config.json",

  // Models
  "model": "provider/model-id",         // Default model
  "small_model": "provider/model-id",   // For titles/summaries
  "default_agent": "build",             // Default agent

  // User
  "username": "lewis",
  "theme": "default",

  // Sharing
  "share": "manual",                    // "manual" | "auto" | "disabled"

  // Updates
  "autoupdate": true,                   // true | false | "notify"

  // Providers
  "provider": {
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    }
  },
  "disabled_providers": [],
  "enabled_providers": [],              // Whitelist mode

  // Agents
  "agent": {
    "my-agent": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a specialist...",
      "mode": "subagent",
      "steps": 20
    }
  },

  // MCP Servers
  "mcp": {
    "local-server": {
      "type": "local",
      "command": ["node", "server.js"],
      "environment": { "KEY": "value" },
      "timeout": 5000
    },
    "remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  },

  // Permissions
  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": { "src/**": "allow", "*.env": "deny" },
    "bash": { "git*": "allow", "rm*": "deny" }
  },

  // Commands
  "command": {},

  // Plugins
  "plugin": ["@opencode/my-plugin"],

  // LSP
  "lsp": {},                            // false to disable

  // File Watching
  "watcher": { "ignore": ["node_modules"] },

  // Instructions
  "instructions": ["./AGENTS.md"],      // Additional prompt files

  // Compaction
  "compaction": {
    "auto": true,                       // Auto-compact when context full
    "prune": true                       // Prune old tool outputs
  },

  // TUI
  "tui": {
    "scroll_speed": 3,
    "diff_style": "auto"               // "auto" | "stacked"
  },

  // Server
  "server": {
    "port": 3000,
    "hostname": "127.0.0.1",
    "mdns": false,
    "cors": []
  },

  // Experimental
  "experimental": {
    "hook": {},
    "batch_tool": false,
    "primary_tools": [],
    "mcp_timeout": 5000
  }
}

Variable Substitution

• {env:VAR_NAME} -- Replace with environment variable
• {file:path/to/file} -- Inline file contents

Agent Configuration

Built-in Agents

Custom Agent Format (.opencode/agent/*.md)

---
description: When to invoke this agent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.7
mode: "subagent"
steps: 20
color: "#FF5733"
hidden: false
disable: false
permission:
  read: allow
  edit: deny
  bash:
    "*": ask
    "git*": allow
---

Your system prompt here. This agent specializes in...

Built-in Tools

Core

Advanced

Web & Search

Interaction

Custom Tools (.opencode/tool/*.{ts,js})

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "What this tool does",
  args: {
    query: tool.schema.string().describe("Search query"),
  },
  async execute(args, context) {
    // context.sessionID, context.messageID, context.agent
    // context.metadata({ title: "...", metadata: {...} })
    // await context.ask({ permission, patterns, always, metadata })
    return "Tool output"
  }
})

Custom Commands (.opencode/command/*.md)

---
description: Brief description
agent: build
model: provider/model
subtask: true
---

Do something with the current code.

## Context
<!-- Dynamic shell commands go here using the ! prefix with backticks -->

Dynamic sections use the exclamation mark prefix with backticks to inline shell command output.

MCP Server Configuration

Local Server (stdio)

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["node", "/path/to/server.js"],
      "environment": { "API_KEY": "{env:MY_KEY}" },
      "enabled": true,
      "timeout": 5000
    }
  }
}

Remote Server (HTTP)

{
  "mcp": {
    "remote": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ..." },
      "oauth": {
        "clientId": "...",
        "clientSecret": "...",
        "scope": "read write"
      }
    }
  }
}

Permission System

Permission rules use glob/prefix matching:

{
  "permission": {
    "*": "ask",                    // Default: ask for everything
    "read": "allow",              // Allow all reads
    "edit": {
      "src/**": "allow",          // Allow editing src/
      "*.env": "deny"             // Deny editing .env files
    },
    "bash": {
      "git*": "allow",            // Allow git commands
      "rm*": "deny",              // Deny rm commands
      "*": "ask"                  // Ask for everything else
    },
    "external_directory": {
      "/tmp/*": "allow"           // Allow operations outside project
    }
  }
}

Values: "allow" | "ask" | "deny"

Plugin System

Plugin Hooks

Plugin Format

Plugins export hooks and tools from TypeScript/JavaScript modules. Install via plugin array in config or place in .opencode/plugin/.

Environment Variables

Core

Authentication

Feature Flags

Claude Code Compatibility

Experimental

HTTP Server API

OpenCode exposes a full REST API (96 operations) when running in server mode (opencode serve). The API uses Hono, supports Basic Auth, SSE for real-time events, and WebSocket for PTY sessions.

Full API reference: See references/http-api.md

Key API Groups

Quick Examples

# Health check
curl http://localhost:4096/global/health

# List sessions
curl -u opencode:$PASSWORD http://localhost:4096/session

# Send a prompt (streaming)
curl -u opencode:$PASSWORD -X POST http://localhost:4096/session/$SID/message \
  -H 'Content-Type: application/json' \
  -d '{"parts":[{"type":"text","text":"fix the bug"}]}'

# Subscribe to events (SSE)
curl -u opencode:$PASSWORD -N http://localhost:4096/event

# PTY WebSocket
websocat ws://localhost:4096/pty/$PID/connect

Typical Workflows

Quick One-Shot Task

opencode run "fix the typo in README.md"
opencode run -m openai/gpt-4.1 "explain the auth flow"
opencode run --format json "list all API endpoints" > endpoints.json

Interactive Development (TUI)

opencode                                 # start TUI
opencode -m anthropic/claude-sonnet-4-20250514  # with specific model
opencode -c                              # continue last session
opencode -s abc123                       # continue specific session

Headless Server + Web

# Terminal 1: start server
OPENCODE_SERVER_PASSWORD=secret opencode serve --port 3000

# Terminal 2: attach
opencode attach http://localhost:3000

# Or use web interface
opencode web --port 3000

PR Review

opencode pr 123                          # checkout PR #123 and start review

Session Export/Import

opencode export abc123 > session.json    # export session
opencode import session.json             # import on another machine

GitHub Actions Agent

opencode github install                  # set up GitHub Actions
# PRs and issues now get AI-assisted responses

Custom Agent Workflow

# Create agent
cat > .opencode/agent/security-reviewer.md << 'EOF'
---
description: Security code review specialist
model: anthropic/claude-sonnet-4-20250514
mode: subagent
permission:
  read: allow
  edit: deny
  bash:
    "git*": allow
    "*": deny
---

You are a security-focused code reviewer. Analyze code for OWASP Top 10
vulnerabilities, credential leaks, injection risks, and authentication flaws.
EOF

# Use it
opencode run --agent security-reviewer "review the auth module"

Multi-Provider Setup

// opencode.jsonc
{
  "provider": {
    "anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } },
    "openai": { "options": { "apiKey": "{env:OPENAI_API_KEY}" } },
    "google": { "options": { "apiKey": "{env:GOOGLE_API_KEY}" } }
  },
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "openai/gpt-4.1-mini"
}

Anti-Patterns

Best Practices

Configuration

• Use project-level config (opencode.jsonc) for project-specific settings
• Use global config (~/.config/opencode/opencode.jsonc) for personal preferences
• Set small_model to a cheap/fast model for titles and summaries
• Enable compaction.auto to handle long sessions gracefully
• Use {env:VAR} and {file:path} for secrets and dynamic values

Agents

• Use plan agent first for complex tasks -- it's read-only and deliberate
• Create custom agents for repeated workflows (security review, docs, etc.)
• Set appropriate permissions -- deny edit/bash for review-only agents
• Set steps limit to prevent runaway agents

Sessions

• Use -c to continue sessions rather than starting fresh
• Export important sessions before they're compacted
• Use --title for meaningful session names

Server Mode

• Always set OPENCODE_SERVER_PASSWORD when using serve
• Use --mdns for LAN discovery in team settings
• Use opencode web for browser-based access

Debugging

• opencode debug config to verify resolved configuration
• opencode debug paths to find data/config/cache locations
• opencode debug agent <name> to inspect agent setup
• --print-logs --log-level DEBUG for troubleshooting

Troubleshooting

"Model not found"

Cause: Provider not configured or model ID incorrect
Fix:
  opencode models                    # list available models
  opencode models --refresh          # refresh from providers
  opencode debug config              # check provider config

"Permission denied" on tool use

Cause: Permission rules blocking tool access
Fix:
  opencode debug config              # check permission section
  # Update opencode.jsonc permission rules

Server won't start

Cause: Port in use or missing password
Fix:
  opencode serve --port 3001         # try different port
  OPENCODE_SERVER_PASSWORD=pw opencode serve  # set password

MCP server connection failed

Cause: Server not running or OAuth expired
Fix:
  opencode mcp ls                    # check server status
  opencode mcp debug <name>          # debug connection
  opencode mcp auth <name>           # re-authenticate

Session won't continue

Cause: Session ID wrong or data corrupted
Fix:
  opencode session list              # find correct session
  opencode session list --format json  # get session IDs
  opencode run -s <correct-id>       # continue with right ID

High token costs

Cause: Expensive model, no compaction, long sessions
Fix:
  opencode stats --days 7 --models   # identify costly models
  # Set small_model for titles/summaries
  # Enable compaction.auto and compaction.prune
  # Use cheaper models for simple tasks

Guidelines

• When the user asks to run opencode, check if they want TUI (opencode), non-interactive (opencode run), or server mode (opencode serve)
• When configuring providers, always use {env:VAR} for API keys, never hardcode
• When creating agents, use .opencode/agent/*.md with YAML frontmatter and markdown prompt body
• When adding MCP servers, verify with opencode mcp ls after configuration
• When debugging issues, start with opencode debug config and opencode debug paths
• When the user mentions costs, point them to opencode stats --days 7 --models --tools
• When managing sessions, remind about -c for continuation and export for preservation
• For CI/automation, always use opencode run --format json
• OpenCode reads .claude/skills/ by default -- disable with OPENCODE_DISABLE_CLAUDE_CODE_SKILLS

Skill Version: 1.0.0 Last Updated: January 2026 OpenCode Version Support: 1.1.31+ Status: Production-Ready