OpenCode Integration Reference

OpenCode (opencode.ai, github.com/anomalyco/opencode)

Executive Summary

OpenCode has significant features Claude Code doesn't have:

• Extended thinking across 7+ providers (Anthropic, OpenAI, Google, Bedrock, etc.)
• LSP integration for code intelligence
• Session compaction with auto-summarization
• 12+ plugin hooks for deep customization
• Permission wildcards with cascading approval
• Event bus for pub-sub across all operations

---

Quick Facts

---

What Our Installer Does

When user runs agentsys and selects OpenCode:

~/.agentsys/                    # Full package copy

~/.config/opencode/commands/         # 10 commands (global)
├── next-task.md
├── delivery-approval.md
├── ship.md
├── deslop.md
├── enhance.md
├── audit-project.md
├── drift-detect.md
├── repo-intel.md
├── sync-docs.md
└── perf.md

~/.config/opencode/agents/           # 29 agents (global)
├── task-discoverer.md
├── exploration-agent.md
├── planning-agent.md
├── implementation-agent.md
├── prepare-delivery:delivery-validator.md
└── ...

~/.config/opencode/skills/           # 24 skills (global)
├── task-discovery/SKILL.md
├── orchestrate-review/SKILL.md
├── deslop/SKILL.md
└── ...

~/.config/opencode/plugins/          # Native plugin (global)
└── agentsys.ts

Native Plugin Features:

• Auto-thinking selection (adjusts budget per agent)
• Workflow enforcement (blocks git push until /ship)
• Session compaction with state preservation
• Provider-agnostic thinking config

---

Model Selection

OpenCode Model Format

provider/model

Examples:

• opencode/claude-opus-4-5 - Via OpenCode's proxy
• anthropic/claude-opus-4-5 - Direct Anthropic
• openai/gpt-4o - OpenAI
• groq/llama-3.3-70b - Groq

Specifying Model in Commands

OpenCode commands can specify model in frontmatter:

---
description: Complex analysis task
agent: general
model: opencode/claude-opus-4-5
subtask: true
---

Specifying Model in Agents

# .opencode/agents/my-agent.md
---
description: Deep analysis agent
mode: subagent
model: opencode/claude-opus-4-5
temperature: 0.7
steps: 50
permission:
  edit: allow
  bash: ask
---

System prompt content here...

Per-Agent Config in opencode.json

{
  "agent": {
    "build": {
      "model": "opencode/claude-opus-4-5"
    },
    "triage": {
      "model": "opencode/claude-haiku-4-5"
    }
  }
}

---

User Interaction Differences

The Checkbox Problem

Claude Code - AskUserQuestion renders as interactive checkboxes:

[x] Option A (Recommended)
[ ] Option B
[ ] Option C

OpenCode - Questions render as numbered list:

1) Option A
2) Option B
3) Option C

Your selection: _

OpenCode Question API

// OpenCode's Question format
{
  question: "Which task source?",
  header: "Task Source",           // max 30 chars
  options: [
    { label: "GitHub Issues", description: "Fetch from gh issues" },
    { label: "Linear", description: "Fetch from Linear" }
  ],
  multiple: true,    // Allow multi-select (comma-separated numbers)
  custom: true       // Allow typing custom answer
}

Implication for AgentSys

Our agents use AskUserQuestion which works in both platforms, but:

• Claude Code: Beautiful checkbox UI
• OpenCode: Functional numbered list

No code changes needed - the functionality works, just different UI.

---

Command Format Comparison

Claude Code Format (Current)

---
description: Task description
argument-hint: "[filter] [--status]"
allowed-tools: Bash(git:*), Read, Write, Task
---

# Command Title

Instructions...

OpenCode Format

---
description: Task description
agent: general              # Which agent handles this
model: opencode/claude-opus-4-5  # Optional model override
subtask: true               # Run as subtask (background)
---

Instructions with $1, $2, $ARGUMENTS placeholders...

Key Differences

---

Agent System

Built-in OpenCode Agents

Agent Modes

• primary - Can be default agent for sessions
• subagent - Called via @ mention syntax (e.g., @agent-name prompt)
• all - Both primary and subagent

Invoking Subagents in OpenCode

OpenCode does NOT have Claude Code's Task tool. Instead, use @ mention syntax:

@general help me search for authentication patterns
@explore find all files that handle user sessions

Subagents can be invoked:

1. Manually - Type @agent-name followed by your prompt
2. Automatically - Primary agents may call subagents based on their descriptions

Navigate between sessions with +Right/Left keybinds.

Custom Agent Definition

# .opencode/agents/opus-reviewer.md
---
description: Deep code review with Opus
mode: subagent
model: opencode/claude-opus-4-5
color: "#FF6B6B"
temperature: 0.3
steps: 100
permission:
  read: allow
  edit: ask
  bash: deny
---

You are a senior code reviewer. Analyze code thoroughly...

---

MCP Integration

OpenCode supports MCP (Model Context Protocol) for external tool integration.

Local Server Example

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["node", "/path/to/server.js"],
      "enabled": true
    }
  }
}

Remote Server Example

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

Note: AgentSys uses native OpenCode commands, agents, and skills instead of MCP for better integration and features like auto-thinking selection.

---

Skill System

Skill Location

OpenCode searches these locations:

1. .opencode/skills/<name>/SKILL.md (project)
2. ~/.config/opencode/skills/<name>/SKILL.md (global)
3. .claude/skills/<name>/SKILL.md (Claude Code compatibility)
4. ~/.claude/skills/<name>/SKILL.md (Claude Code compatibility)

---

name: my-skill description: When to use this skill

Skill content and instructions...

### Compatibility

Our skills are installed to `~/.config/opencode/skills/` for global access.
OpenCode also scans `.claude/skills/` for Claude Code compatibility.

---

## Configuration Hierarchy

**Merge order (lowest to highest priority):**
1. Remote org configs (`.well-known/opencode`)
2. Global: `~/.config/opencode/opencode.json`
3. Custom path: `OPENCODE_CONFIG` env var
4. Project: `opencode.json` in project root
5. Inline: `OPENCODE_CONFIG_CONTENT` env var

### Variable Substitution

```jsonc
{
  "provider": {
    "anthropic": {
      "api_key": "{env:ANTHROPIC_API_KEY}"
    }
  }
}

---

Permission System

Permission Actions

• allow - Always allow
• deny - Always deny
• ask - Prompt user each time

Pattern-Based Permissions

{
  "permission": {
    "edit": {
      "*.env": "ask",
      "*.env.example": "allow",
      "*": "allow"
    },
    "bash": "ask",
    "external_directory": "deny"
  }
}

Per-Agent Permissions

# In agent definition
permission:
  read: allow
  edit: ask
  bash: deny
  glob: allow
  grep: allow

---

Project Instructions

Rules Discovery

OpenCode applies rules from these sources:

1. Project rules: AGENTS.md
2. Global rules: ~/.config/opencode/AGENTS.md

Claude Code compatibility fallbacks:

• If no project AGENTS.md exists: CLAUDE.md
• If no global ~/.config/opencode/AGENTS.md exists: ~/.claude/CLAUDE.md

You can also configure additional instruction files via the instructions array in opencode.json (for example, with glob patterns in monorepos).

Generating AGENTS.md

# In OpenCode
/init

Creates AGENTS.md with project context.

---

Known Limitations

UI Differences (Not Fixable)

1. Questions show as numbers, not checkboxes - OpenCode limitation
2. No rich markdown in responses - Terminal rendering

Functional Gaps

1. No hook system - OpenCode has plugins with hooks, but different from Claude Code hooks
2. No marketplace - Manual installation only
3. No Task tool - OpenCode uses @ mentions for subagent invocation, not Task tool

Workarounds

---

Testing OpenCode Integration

Verify MCP Connection

# In OpenCode session
# Use any MCP tool
workflow_status

Verify Commands

# Should list AgentSys commands
/next-task
/deslop
/ship

Verify State Directory

# After running workflow
ls .opencode/
# Should see: tasks.json, flow.json (in worktree)

---

Improvement Opportunities

Short Term

1. Add model: hints to complex commands for better OpenCode experience
2. Document the numbered-list vs checkbox difference
3. Add OpenCode-specific examples to USAGE.md

Medium Term

1. Create native OpenCode agent definitions (.opencode/agents/)
2. Add OpenCode plugin with hooks for workflow enforcement
3. Test with different model providers

Long Term

1. OpenCode-native UI for task selection
2. Integrate with OpenCode's built-in agents
3. Cross-platform state sync

---

---

Extended Thinking / Reasoning Configuration

OpenCode supports thinking/reasoning across multiple providers with different APIs.

Provider-Specific Thinking Config

Configuring Extended Thinking

Per-Agent (in opencode.json):

{
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250929",
      "options": {
        "thinking": {
          "type": "enabled",
          "budgetTokens": 16000
        }
      }
    },
    "explore": {
      "model": "openai/gpt-5.1",
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "auto"
      }
    }
  }
}

Via Plugin Hook (runtime):

"chat.params": async (input, output) => {
  if (input.agent === "planning-agent") {
    output.options.thinking = { type: "enabled", budgetTokens: 16000 }
  }
}

Cycle at Runtime: Press Ctrl+T to cycle through available thinking variants.

---

Question API Details

Format Comparison

CRITICAL: Label Length OpenCode enforces a 30-character limit on option labels. Truncate task titles:

function truncateLabel(num, title) {
  const prefix = `#${num}: `;
  const maxTitleLen = 30 - prefix.length;
  return title.length > maxTitleLen
    ? prefix + title.substring(0, maxTitleLen - 1) + '...'
    : prefix + title;
}

OpenCode Question Schema

{
  question: string,           // Full question text
  header: string,             // Label (max 30 chars)
  options: [
    { label: string, description: string }
  ],
  multiple?: boolean,         // Allow multi-select
  custom?: boolean            // Allow custom answer (default: true)
}

Adapting Our AskUserQuestion Calls

Our agents use Claude's AskUserQuestion format. For OpenCode compatibility:

// Claude Code format (current)
{
  questions: [{
    question: "Which task source?",
    header: "Source",        // max 12 chars
    multiSelect: false,
    options: [
      { label: "GitHub Issues", description: "..." }
    ]
  }]
}

// OpenCode equivalent
{
  questions: [{
    question: "Which task source?",
    header: "Task Source",   // max 30 chars - can be more descriptive
    multiple: false,
    custom: true,
    options: [
      { label: "GitHub Issues", description: "..." }
    ]
  }]
}

Key Insight: The formats are similar enough that Claude's AskUserQuestion tool works in OpenCode - it just renders as numbered list instead of checkboxes.

---

Plugin Hooks (Deep Customization)

OpenCode has 12+ hooks for intercepting and modifying behavior.

Hook Categories

Chat Hooks:

Tool Hooks:

Permission Hook:

Experimental Hooks:

Example: Workflow Enforcement via Hooks