Opencode

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

┌─────────────────────────────────────────────────────────────────┐
│                         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)

# 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

opencode --version

Configuration

Configuration Files

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

{
  "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

# 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

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

Creating Custom Agents

Interactive Creation

opencode 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)

{
  "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:

---
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:

---
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

---
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

---
description: Review recent changes
---

Review the following git diff:

`!git diff HEAD~1`

Summarize changes and identify any issues.

File References

---
description: Explain architecture
---

Based on the architecture documentation:

@ARCHITECTURE.md

Explain how the authentication system works.

CLI Reference

TUI Mode (Default)

# 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

# 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

# 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

# Create new agent
opencode agent create

# List all agents
opencode agent list

MCP Integration

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

# List MCP servers
opencode mcp list

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

Session Management

# 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

opencode
/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:

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

Common Use Cases

Code Review Agent

---
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

---
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

---
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

Issue: 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

Issue: 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

Issue: 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

Issue: 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