---

name: opencode version: "1.0.0" description: OpenCode - Open source AI coding agent for terminal, desktop, and IDE with multi-provider LLM support, custom agents, MCP integration, and granular permissions

OpenCode Skill

OpenCode is an open source AI coding agent available as a terminal interface (TUI), desktop app, or IDE extension. It enables developers to work on code projects through conversational interactions with intelligent assistance for code explanation, implementation planning, code modification, and more.

Key Value Proposition: A flexible, multi-provider AI assistant with customizable agents, granular permissions, and extensive tool integrations that can be tailored for specific workflows like code review, documentation, security auditing, or development.

When to Use This Skill

• Setting up OpenCode for a new development environment
• Creating custom agents for specialized coding workflows
• Configuring permissions for team-based development
• Building automated scripts with OpenCode CLI
• Integrating MCP servers for extended capabilities
• Troubleshooting OpenCode configuration or tool issues
• Comparing OpenCode features with other AI coding assistants

When NOT to Use This Skill

• For Claude Code/Claude CLI specific features (different product)
• For GitHub Copilot configuration (use copilot-specific docs)
• For Cursor IDE settings (different AI editor)
• For generic LLM API usage (use provider-specific skills)

---

Core Concepts

Architecture Overview

Copy┌─────────────────────────────────────────────────────────────────┐
│                         OpenCode                                 │
│            Terminal UI / Desktop App / IDE Extension             │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│    Agents     │    │    Tools      │    │  Permissions  │
├───────────────┤    ├───────────────┤    ├───────────────┤
│ • Build       │    │ • read/write  │    │ • allow       │
│ • Plan        │    │ • edit/patch  │    │ • ask         │
│ • Custom...   │    │ • bash        │    │ • deny        │
│ • Subagents   │    │ • grep/glob   │    │ • Wildcards   │
└───────────────┘    │ • webfetch    │    └───────────────┘
                     │ • lsp         │
                     │ • MCP servers │
                     └───────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  LLM Providers │   │   Sessions    │    │   Commands    │
├───────────────┤    ├───────────────┤    ├───────────────┤
│ • OpenAI      │    │ • SQLite      │    │ • /init       │
│ • Claude      │    │ • Persistence │    │ • /undo       │
│ • Gemini      │    │ • Export/     │    │ • /share      │
│ • Groq        │    │   Import      │    │ • Custom...   │
│ • Bedrock     │    └───────────────┘    └───────────────┘
└───────────────┘

Agent Types

---

Installation

Quick Install (Recommended)

Copy# Install script
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# Homebrew (macOS/Linux)
brew install opencode-ai/tap/opencode

# npm
npm install -g opencode

# Go
go install github.com/opencode-ai/opencode@latest

Verify Installation

Copyopencode --version

---

Configuration

Configuration Files

OpenCode uses opencode.json in your project root or global config at ~/.config/opencode/:

Copy{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "agent": {
    "build": {
      "model": "claude-sonnet-4-20250514"
    },
    "plan": {
      "model": "claude-sonnet-4-20250514",
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Environment Variables

Copy# API Keys (choose your provider)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
export GROQ_API_KEY="..."

# OpenCode Settings
export OPENCODE_CONFIG="~/.config/opencode/opencode.json"
export OPENCODE_PERMISSION="ask"  # Default permission level
export OPENCODE_AUTO_SHARE="true"  # Auto-share sessions
export OPENCODE_EXPERIMENTAL_LSP_TOOL="true"  # Enable LSP

---

Tools Reference

Built-in Tools

Tool Configuration

Copy{
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "list": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    }
  }
}

---

Creating Custom Agents

Interactive Creation

Copyopencode agent create

This guides you through:

1. Selecting storage location (global or project)
2. Defining agent purpose
3. Auto-generating system prompts
4. Choosing accessible tools
5. Creating markdown configuration

Agent Configuration (JSON)

Copy{
  "agent": {
    "reviewer": {
      "description": "Code review specialist",
      "mode": "subagent",
      "model": "claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": ".opencode/agent/reviewer.md",
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "edit": false,
        "bash": false
      },
      "permission": {
        "webfetch": "deny"
      },
      "maxSteps": 20
    }
  }
}

Agent Configuration (Markdown)

Create .opencode/agent/reviewer.md:

Copy---
description: Code review specialist for quality and security
mode: subagent
model: claude-sonnet-4-20250514
temperature: 0.3
tools:
  read: true
  grep: true
  glob: true
  edit: false
  bash: false
---

You are a code review specialist focused on:

1. Code quality and best practices
2. Security vulnerabilities
3. Performance issues
4. Maintainability concerns

When reviewing code:
- Identify issues by severity (critical, major, minor)
- Provide specific line references
- Suggest concrete improvements
- Consider the project's existing patterns

Agent Parameters

---

Custom Commands

Command Structure

Create .opencode/command/review.md:

Copy---
description: Review code changes
agent: reviewer
---

Review the following code changes:

$ARGUMENTS

Focus on:
1. Security vulnerabilities
2. Performance issues
3. Code style violations
4. Missing tests

Using Arguments

Copy---
description: Create a component
---

Create a new React component named $1 in the $2 directory.

Requirements:
- TypeScript
- Styled with Tailwind
- Include tests

Usage: /component Button components/ui

Including Shell Output

Copy---
description: Review recent changes
---

Review the following git diff:

`!git diff HEAD~1`

Summarize changes and identify any issues.

File References

Copy---
description: Explain architecture
---

Based on the architecture documentation:

@ARCHITECTURE.md

Explain how the authentication system works.

---

CLI Reference

TUI Mode (Default)

Copy# Start in current directory
opencode

# Start in specific project
opencode /path/to/project

# Continue last session
opencode --continue

# Use specific session
opencode --session <session-id>

# Override model
opencode --model claude-sonnet-4-20250514

Non-Interactive Mode

Copy# Run single prompt
opencode run "explain this codebase"

# Run with file context
opencode run --file src/main.ts "add error handling"

# Run custom command
opencode run --command review

# Output format
opencode run --format json "list all functions"

Server Mode

Copy# Start headless server
opencode serve --port 8080

# Start with web interface
opencode web --port 8080

# Connect to remote server
opencode attach http://localhost:8080

Agent Management

Copy# Create new agent
opencode agent create

# List all agents
opencode agent list

MCP Integration

Copy# Add MCP server
opencode mcp add <server-name>

# List MCP servers
opencode mcp list

# Debug MCP connection
opencode mcp debug <server-name>

Session Management

Copy# List sessions
opencode session list --max-count 10

# Export session
opencode export <session-id>

# Import session
opencode import session.json

# View usage stats
opencode stats --days 7

---

Project Initialization

Generate AGENTS.md

Copyopencode
/init

This analyzes your project and generates AGENTS.md containing:

• Project structure overview
• Key patterns and conventions
• Technology stack
• Important files and directories

Best Practice: Commit AGENTS.md to version control so OpenCode understands your codebase.

---

Permissions System

Permission Levels

Approval Responses

When prompted:

• once - Approve single request
• always - Approve matching requests for session
• reject - Deny the request

Default Permissions

Most tools default to allow, except:

• doom_loop - ask (safety feature)
• external_directory - ask (safety feature)
• .env* files - deny (security)

Agent-Level Overrides

Agent permissions take precedence over global:

Copy{
  "permission": {
    "bash": "ask"
  },
  "agent": {
    "build": {
      "permission": {
        "bash": "allow"
      }
    }
  }
}

---

Common Use Cases

Code Review Agent

Copy---
description: Systematic code review
mode: subagent
tools:
  read: true
  grep: true
  edit: false
  bash: false
---

You are a code reviewer. For each review:

1. Check for security vulnerabilities
2. Identify performance bottlenecks
3. Ensure code follows project patterns
4. Verify test coverage
5. Suggest improvements

Format findings as:
- CRITICAL: [issue]
- MAJOR: [issue]
- MINOR: [issue]

Documentation Agent

Copy---
description: Documentation writer
mode: subagent
tools:
  read: true
  glob: true
  write: true
  bash: false
---

You write clear, comprehensive documentation.

When documenting:
1. Follow project's existing doc style
2. Include code examples
3. Document edge cases
4. Keep language accessible

Security Audit Agent

Copy---
description: Security vulnerability scanner
mode: subagent
tools:
  read: true
  grep: true
  bash: false
  webfetch: true
---

You are a security auditor. Scan for:

1. Injection vulnerabilities (SQL, XSS, command)
2. Authentication/authorization issues
3. Sensitive data exposure
4. Insecure dependencies
5. Misconfigurations

Reference OWASP Top 10 for classification.

---

Troubleshooting

Agent Not Invoking

CopyIssue: Custom agent doesn't respond to @mention

Solutions:

1. Verify agent file is in correct location (.opencode/agent/ or ~/.config/opencode/agent/)
2. Check mode is set correctly (subagent for @mentions)
3. Ensure YAML frontmatter is valid
4. Try opencode agent list to verify registration

Permission Denied

CopyIssue: Tool execution blocked unexpectedly

Solutions:

1. Check global permissions in opencode.json
2. Verify agent-specific overrides
3. Use opencode run --permission allow for testing
4. Check for conflicting wildcard patterns

Tool Not Working

CopyIssue: grep/glob returns no results

Solutions:

1. Check if files are in .gitignore (excluded by default)
2. Create .ignore file to include ignored directories
3. Verify pattern syntax is correct

LLM Connection Issues

CopyIssue: Provider not responding

Solutions:

1. Verify API key is set correctly
2. Check network connectivity
3. Run opencode models to list available models
4. Try opencode models --refresh to refresh cache

---

Resources

Official Documentation

• OpenCode Docs
• Agents Guide
• Tools Reference
• Permissions
• CLI Reference

Source Code

• GitHub Repository

Related Projects

• Charm - Terminal UI framework
• MCP Protocol - Model Context Protocol

---

Version History

• 1.0.0 (2026-01-12): Initial skill release
  • Complete OpenCode agent system documentation
  • Built-in and custom agent configuration
  • Tools reference with permission system
  • CLI commands and usage patterns
  • Custom commands and SKILL.md integration
  • MCP server integration
  • Common agent templates (review, docs, security)
  • Troubleshooting guide