OpenCode: The Universal ACP Adapter
Run OpenCode as a first-class coding agent in CodeMantis — open models through your own providers, driven through the Agent Client Protocol.
Overview
OpenCode is CodeMantis's third first-class coding agent, alongside Claude Code and OpenAI Codex. CodeMantis drives it through the Agent Client Protocol (ACP) — a universal adapter that lets one interface speak to more than one agent.
Like the other two agents, OpenCode is chosen per session. Unlike them, it isn't tied to a single vendor subscription: it runs open models through providers you configure — OpenRouter, a local Ollama or LM Studio endpoint, or the free OpenCode Zen gateway. That makes it the agent to reach for when you want to run a local model, spread work across a separate pool, or try something the two vendor CLIs don't offer.
Everything else you already know still applies. Tool approvals, history & resume, SpecWriter, the Assistant panel, and Self-Drive all work exactly as they do for Claude Code and Codex.
Running an OpenCode Session
Install and configure OpenCode
Install the CLI and add at least one provider on the OpenCode card. See Installing OpenCode for the full walkthrough.
Start a session and pick OpenCode
In the agent picker, choose OpenCode — it's marked with an ACP badge.
Work as usual
Assistant text streams into the chat, thoughts go to the Reasoning panel, and file reads, edits, and commands land in the Activity Feed — the same three-panel flow as every other agent.
A few surfaces adapt to what OpenCode advertises over ACP:
The model chip is read-only
The model chip on a running session shows which model you're using but can't be changed there (a tooltip says so). Change the model for future sessions in Settings › Agents › OpenCode.
Plan mode
The Mode pill lists the usual modes, and Plan drives OpenCode's native plan mode — "Disallows all edit tools" — on the live session. It appears only when the running agent offers a plan-equivalent mode, and OpenCode ships one built in. Leaving Plan restores the agent's default mode.
While planning, your prompts carry a plan-document contract: when the plan is final, the model wraps it between ===PLAN-DOCUMENT-BEGIN=== and ===PLAN-DOCUMENT-END=== marker lines. CodeMantis detects them, saves the document into the project's plans/ folder (OpenCode can't write files in plan mode), exits plan mode, and offers Implement Now via the Plan Complete modal.
Image attachments
The image-attach control appears only when the selected provider and model accept images.
No slash-command overlay
OpenCode has no CLI slash-command equivalent, so there is no slash-command overlay for OpenCode sessions.
Approvals, history, and Self-Drive
Tool approvals (Approve / Deny), history & resume, SpecWriter, and the Assistant panel behave identically to Claude Code and Codex. Self-Drive's Auto-Accept mode auto-approves OpenCode's tool requests. Closed OpenCode sessions appear in History with an OC badge and resume in place.
Configuring Providers & Models
OpenCode needs at least one provider to reach a model. On the OpenCode card:
- Add a provider — OpenRouter (paste an API key), a local endpoint like Ollama or LM Studio (no key needed), or a custom OpenAI-compatible URL.
- Pick a model — the dropdown is filled live from
opencode models; there is no hard-coded list. Free-text entry (provider/model) is always available, and a Refresh re-runs the catalog.
The model you set here applies to new OpenCode sessions.
API keys are encrypted at rest and shown masked (••• + last 4). They are injected only as environment variables when a session starts, and are never written to opencode.json, logs, or the agent connection. If a session fails because a provider key is missing, the error carries an Open OpenCode settings button to fix it in place.
How It Fits Per-Task Routing
Because OpenCode is a first-class agent, it slots into the same surfaces as Claude Code and Codex. When it's installed and a provider is configured, it appears in the per-session agent picker and in Settings › Agents, and can be chosen per session or routed per task the same way — main_chat, spec_writer, assistant, and help.
Self-Drive is not a task category. It always inherits the agent of the session it attaches to. If a session is on OpenCode, Self-Drive runs on OpenCode too — its Auto-Accept mode auto-approves OpenCode's tool requests. See Per-Task Agent Routing for the full routing reference and Choosing Your Coding Agent for when to reach for each.
Tips
- Set your model before you start. The in-session model chip is read-only — choose the model in Settings › Agents › OpenCode first, since it applies to new sessions.
- Refresh the catalog after adding a provider. The model dropdown is populated live from
opencode models; if a newly added provider's models don't appear, hit Refresh. - Go local or free. Point a provider at Ollama or LM Studio (no key needed), or use the free OpenCode Zen gateway, when you'd rather not draw on a paid pool.
- Use Plan mode for read-only planning. CodeMantis saves the finished plan to the project's
plans/folder and offers Implement Now. - Let Self-Drive drive it. Auto-Accept auto-approves OpenCode's tool requests, exactly as it does for the other agents.
- CodeMantis never touches your
opencode.json. A broken config is reported, not overwritten — fix it and re-check.
Related Articles
- Installing OpenCode — Install the CLI and configure providers and models
- Choosing Your Coding Agent — When to pick Claude Code, Codex, or OpenCode
- Per-Task Agent Routing — Route different task categories to different agents
- Self-Drive: Autonomous Implementation — Run an entire Implementation Guide automatically on any agent
- Session Modes Explained — How Plan and the other modes work across agents
- OpenCode Not Found — Troubleshoot detection issues