Skip to content

OpenCode CLI Configuration

Sample configurations for the OpenCode CLI, and a guide to the configuration format they use.

OpenCode combines multiple AI models, custom commands, and specialized agents in a terminal workflow. The samples show two ways to set that up.

Note

The samples use the native OpenCode V2 format: agents (not agent), commands (not command), ordered permissions rules (not tools/permission maps), and MCP servers under mcp.servers. V2 loads project guidance from AGENTS.md only. The Configuration Guide is the full reference.

The samples

The samples live in harness/opencode-samples/ in the repository, not on this site.

Sample Directory Best for
Standard standard-config/ A few agents, commands, permissions, and an MCP server in one opencode.json
Modular agent-subagent-config/ Many specialized subagents, one Markdown file each, plus plan and build primary agents
MCP servers mcp/ Docker and npx MCP server entries to copy into your config. See MCP Servers

The modular sample's subagents are api, architect, cloud, data, database, devops, documentation, performance, research, reviewer, security, testing, and uxui. Each model and permission set is in the agent's own file in agents/.

For a full multi-agent system built on the same pattern, see the Matrix and Lane topologies.

Install

Run these from a clone of this repository. Both samples use the built-in GitHub Copilot provider, so sign in once with /connect in the OpenCode interface.

# Standard: one file in your project
cp harness/opencode-samples/standard-config/opencode.json ~/your-project/opencode.json

# Or modular: config and plan prompt at the project root, subagents in .opencode/agents/
cp harness/opencode-samples/agent-subagent-config/opencode.json ~/your-project/
cp -r harness/opencode-samples/agent-subagent-config/prompts ~/your-project/
mkdir -p ~/your-project/.opencode/agents
cp harness/opencode-samples/agent-subagent-config/agents/*.md ~/your-project/.opencode/agents/

To apply the standard sample to every project, copy it to ~/.config/opencode/opencode.json instead. The modular sample's plan agent loads {file:./prompts/plan.txt} relative to opencode.json, so keep prompts/ beside it.

The standard sample's GitHub MCP server reads {env:GITHUB_TOKEN}, so set that variable before starting OpenCode:

# Linux and macOS
export GITHUB_TOKEN="your-github-token"

# Windows PowerShell
$env:GITHUB_TOKEN = "your-github-token"

Then start opencode in your project. The standard sample defines /quick-fix, /review, /document, /build, /test, and /deploy.

Where to go next