Integrations

opencode

Run pair on opencode, zero-wiring skill discovery, MCP-native access, headless run/serve, and opencode as a pair-cli run engine.

opencode is a harness for pair's process and an engine pair-cli run can drive. It is the MCP-native harness in pair's framework, and the only one with a persistent headless HTTP server.

This page is the user-facing setup guide. The facts it describes are maintained once, in the agent-harness framework inside the Knowledge Base your agents read: that guide is the source of truth. Run /pair-capability-setup-harness to have pair configure opencode for you.

Prerequisites

  • opencode installed and authenticated (opencode auth list shows a provider)
  • A pair-enabled project (pair-cli install completed, .pair/ exists)

Skill Discovery: Nothing to Wire

opencode searches, in order, .opencode/skills/, .claude/skills/ and .agents/skills/ at the project level (walking up to the git worktree root), plus the matching global paths under ~/.config/opencode/, ~/.claude/ and ~/.agents/. pair-cli install writes the canonical copies to .claude/skills/ and symlinks the rest, so pair's skills are already visible, no wiring.

Skills present both globally and in the project produce a duplicate skill name warning. That is opencode telling you the discovery walk ran, not an error in your project.

Project Context

opencode applies a winner-takes-all rule per category, never a merge: project (AGENTS.md, falling back to CLAUDE.md), global (~/.config/opencode/AGENTS.md, falling back to ~/.claude/CLAUDE.md), and custom (files named in opencode.json's instructions, which add to the winning AGENTS.md). A repository carrying both AGENTS.md and CLAUDE.md never loads both from the same category.

Access Paths

MCP is first-class: opencode mcp add|list|auth|logout|debug manages servers directly. A project whose tech/automation.md declares Requires: mcp is fit for opencode (and, deliberately, not for pi).

Headless Execution

CommandWhat it is
opencode run "<message>"One-shot non-interactive execution; --format json emits the JSONL event stream pair-cli run reads
opencode serveA persistent headless HTTP server: the capability no other harness in this framework has
opencode attach <url>Drives a running server remotely

Driving opencode with pair-cli run

# Resolution only - see the exact command line before anything runs
pair-cli run --engine opencode --root 212 --dry-run
 
# Unattended within a narrow perimeter
pair-cli run --engine opencode --root 212 --autonomous --max-iterations 3

opencode confirms permissions by default, and pair-cli run keeps that posture unless you pass --autonomous (which translates to opencode's own --auto). opencode has no project-trust gate, so there is nothing to approve there.

To make opencode the project's default engine:

{ "engine": { "id": "opencode" } }

Model Providers: Two Gateways, Neither Is an Engine

Provider choice and engine choice are different axes: --engine opencode says which process runs, --model says which model it talks to.

  • Zen: pay-as-you-go, API-key based. Several models are offered free "for a limited time".
  • Go: subscription-based, and spendable headless: obtain a persistent API key once (/connect in the TUI), then use it like any other API key.

Free and experimental models are the data-exposure exception. Most Zen providers are zero-retention, but free/experimental entries may use your data to improve the model; OpenAI/Anthropic-backed entries retain requests for 30 days regardless of tier; some vendors log or train unless declined. Check the specific provider's disclosure before pointing an unattended run at a free model: an unattended run sends far more of your repository than a manual session does.

Verify It Works

opencode run "/pair-next"

Expected: opencode discovers the skills and reports the next action.

Previous

GitHub Copilot

Next

pi

On this page