Skip to content

OpenCode Adapter

Adapter ID: opencode
Source: packages/cli/internal/adapter/opencode.go
Status: stable
Config directory: .opencode

Overview

The OpenCode adapter generates native configuration for the OpenCode CLI. It emits agents, skills, commands, OpenCode-specific mode files, MCP configuration, hooks, and plugins into .opencode/.

Generated Files

Path Description
.opencode/agents/<name>.md Agent definitions (canonical agents with frontmatter rewrite)
.opencode/skills/<name>/SKILL.md Skill directories
.opencode/commands/<name>.md Slash commands
.opencode/modes/<name>.md OpenCode-specific mode files
.opencode/lazyai.mcp.jsonc Legacy MCP config (migration input only; not written by current compiler)
.opencode/plugins/ Plugin hooks
opencode.json Root config with instructions, permissions, and MCP entries
AGENTS.md Root instructions

Supported Asset Types

Asset kind Shape Destination
Agents flat .opencode/agents/<name>.md
Skills dir-per-item .opencode/skills/<name>/SKILL.md
Templates none —
Commands flat .opencode/commands/<name>.md
OpenCode modes flat .opencode/modes/<name>.md
Output styles none —
Prompts none —

MCP Behavior

OpenCode MCP is compiled via CompileMCPForTool. The adapter merges MCP servers into the root opencode.json config file. Legacy .opencode/lazyai.mcp.jsonc entries are read as migration input only; the current compiler does not write that file. User-authored servers are preserved across re-runs.

Hook Behavior

Hooks are installed as OpenCode plugins under .opencode/plugins/. The adapter copies managed plugin files from the LazyAI library into .opencode/plugins/ and does NOT shell out to install external plugins.

Skill Behavior

Skills are written as Agent Skills-compatible directories: .opencode/skills/<name>/SKILL.md. The adapter copies selected skills from the canonical library.

Mode Behavior

Mode files are written under .opencode/modes/<name>.md. Each file uses current OpenCode frontmatter: mode: primary declares the mode type and permission: (with edit/bash/webfetch set to deny) replaces the deprecated tools: boolean map. LazyAI currently treats this as an OpenCode-specific surface rather than a cross-tool abstraction.

Agent Behavior

Canonical agents are written as flat markdown files under .opencode/agents/. The adapter applies frontmatter rewrite for OpenCode compatibility. A default "guide" agent is always installed.

Scope Support

Scope Supported
Project yes
Workspace yes
Global yes

Headless Support

Yes (CanRunHeadless() = true). The adapter supports headless init and validation.

Known Limitations

  • No prompts directory; prompts ship as commands
  • No output-styles concept
  • No documented template surface

Test Coverage

Test file What it verifies
opencode_adapter_test.go Install from FS, global scope, preserves root json, commands+modes, selection filters, instructions key resolution, default agent, skill surface, package.json
opencode_frontmatter_test.go Frontmatter rewrite for OpenCode agents
opencode_validate_test.go Validation of generated opencode.json
opencode_plugin_test.go Plugin installation
internal/library/integration_test.go #561: mode files contain permission: key; deprecated tools: map is absent