OpenCode.ai Tool Skill

Comprehensive reference for OpenCode.ai - an open-source AI coding agent available as terminal interface, desktop application, and IDE extension.

Quick Reference

Installation:

curl -fsSL https://opencode.ai/install | bash
# or
npm install -g opencode

Start OpenCode:

opencode              # Launch TUI in current directory
opencode /path/to/dir # Launch in specific directory
opencode run "prompt" # Non-interactive mode
opencode serve        # Start headless server

Essential Commands:

• /connect - Configure API keys
• /init - Generate AGENTS.md
• /models - List available models
• /share - Share session
• /undo - Undo changes
• Tab - Switch agents
• Ctrl+P - Command palette

Configuration Files:

• ~/.config/opencode/opencode.json - Global config
• ./opencode.json - Project config
• AGENTS.md - Project instructions
• .opencode/agent/ - Custom agents
• .opencode/skill/ - Agent skills
• .opencode/tool/ - Custom tools
• .opencode/command/ - Custom commands

Documentation Index

This skill contains 32 comprehensive documentation modules organized by category.

Core (7 modules)

• Introduction - Installation, setup, primary use cases
• Configuration - JSON configuration options and merge order
• Providers - 75+ LLM providers setup
• Network - Proxy and certificate configuration
• Enterprise - SSO, central config, AI gateway
• Troubleshooting - Common issues and solutions
• Migration 1.0 - Upgrade guide

Usage (7 modules)

• TUI - Terminal interface reference
• CLI - Command-line interface
• IDE - VS Code/Cursor integration
• Zen - Curated model gateway
• Share - Session sharing
• GitHub - GitHub Actions integration
• GitLab - GitLab CI/CD integration

Configuration (14 modules)

• Tools - Built-in and custom tools
• Rules - AGENTS.md instructions
• Agents - Custom agent configuration
• Models - Model selection and variants
• Themes - Custom theme creation
• Keybinds - Keyboard shortcuts
• Commands - Custom slash commands
• Formatters - Code formatting
• Permissions - Tool approval system
• LSP Servers - Language server setup
• MCP Servers - Model Context Protocol
• ACP Support - Agent Client Protocol
• Skills - Reusable instructions
• Custom Tools - TypeScript tools

Development (4 modules)

• SDK - JavaScript/TypeScript client
• Server - HTTP API reference
• Plugins - Plugin development
• Ecosystem - Community projects

See index.md for complete navigation.

Key Concepts

Agent Architecture

Primary Agents - Main assistants you interact with directly:

• Build: Full tools enabled (default)
• Plan: Restricted, analysis-focused

Subagents - Specialized assistants invoked by primary agents:

• General: Research and multi-step tasks
• Explore: Fast codebase exploration

Configuration Hierarchy

1. Command-line flags (highest priority)
2. Environment variables
3. Project config (./opencode.json)
4. Global config (~/.config/opencode/opencode.json)
5. Built-in defaults

Tool Permission Levels

Common Patterns

Basic Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4",
  "agent": {
    "security": {
      "description": "Security auditor",
      "permission": { "edit": "deny" }
    }
  }
}

Custom Command

---
description: Review current changes
agent: plan
---
Review the following changes:
!`git diff --staged`

MCP Server Setup

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

Custom Tool

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

export default tool({
  description: "Query project database",
  args: {
    query: tool.schema.string().describe("SQL query")
  },
  async execute(args) {
    return `Executed: ${args.query}`
  }
})

Resources

• Documentation: https://opencode.ai/docs
• GitHub: https://github.com/anomalyco/opencode
• Discord: https://opencode.ai/discord

Storage Locations:

• Config: ~/.config/opencode/
• Data: ~/.local/share/opencode/
• Cache: ~/.cache/opencode/
• Logs: ~/.local/share/opencode/log/

Works Well With

• moai-lang-typescript - TypeScript development patterns
• moai-lang-python - Python development patterns
• moai-domain-backend - Backend API development
• moai-domain-frontend - Frontend development
• moai-workflow-testing - Testing workflows