Installing OpenCode (Prerequisites)

CodeMantis can use OpenCode as a first-class coding agent alongside Claude Code and OpenAI Codex. This page covers OpenCode setup. You only need one supported CLI installed to start using CodeMantis — but adding OpenCode gives you a third agent to route work to, and one that isn't tied to any single vendor's subscription.

What Is OpenCode?

OpenCode is a command-line coding agent that CodeMantis drives through the Agent Client Protocol (ACP) — the same universal adapter layer that lets CodeMantis talk to more than one agent. Like Claude Code and Codex, OpenCode is chosen per session. Unlike them, it isn't locked to one vendor: it runs open models through providers you configure — OpenRouter, a local Ollama or LM Studio endpoint, or the free OpenCode Zen gateway.

Inside CodeMantis an OpenCode session behaves like any other — assistant text streams into the chat, reasoning goes to the Reasoning panel, and file reads, edits, and commands land in the Activity Feed.

Installation

Install the OpenCode CLI, then let CodeMantis detect it. The OpenCode card shows the install commands and the tested version range, so you never need a terminal beyond the one-time install. The two commands are:

curl -fsSL https://opencode.ai/install | bash

Or, if you have Node.js installed:

npm install -g opencode-ai

The curl | bash script runs in macOS and Linux shells (and in WSL on Windows). The npm install -g opencode-ai command works anywhere Node.js is installed, including native Windows. If neither fits your platform, use the installer from the official OpenCode project.

After installing, open Settings › Agents. The OpenCode card probes your machine and shows one of:

• Installed — ready to use.
• Not installed — a hint with the install commands above and a Re-check button.
• Too old (red banner) — below the minimum supported version; update to continue.
• Newer than tested (amber banner) — runs anyway, with a one-time notice per session.

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. You change it in the same place later — the model chip inside a running session is read-only.

Signing In (Provider Authentication)

OpenCode has no single login command the way Claude Code and Codex do. Instead, you authenticate per provider, right on the OpenCode card:

• OpenRouter — paste your API key.
• A local endpoint (Ollama, LM Studio) — no key needed.
• OpenCode Zen — the free gateway option.
• A custom OpenAI-compatible URL — supply the key that endpoint expects.

Your keys are protected: they 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.

Verify the Installation

CodeMantis detects OpenCode automatically — click Re-check on the OpenCode card if a fresh install hasn't been picked up yet. To confirm the binary is on your PATH from a terminal:

• macOS / Linux:

  which opencode

  You should see a path such as /usr/local/bin/opencode or your npm global bin directory ($(npm config get prefix)/bin).

• Windows (PowerShell):

  Get-Command opencode

  Or in Command Prompt, run where opencode. You should see a path such as %APPDATA%\npm\opencode.cmd.

If the command prints nothing, the CLI is not on your system PATH — fix that below.

Fixing Common PATH Issues

If opencode runs in your terminal but CodeMantis reports it as Not installed, the binary is on disk but not on the PATH the app can see.

macOS (zsh, the default shell)

Add your npm global bin directory to your PATH:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you used the curl | bash installer, add the directory it reported to your PATH the same way. Then run which opencode again to confirm.

Windows

Find your npm global directory:

npm config get prefix

This is typically %APPDATA%\npm. Add that directory to your PATH via System Properties › Environment Variables › Path, then open a new terminal and confirm with Get-Command opencode.

After any PATH change, quit and relaunch CodeMantis so it inherits the updated environment, then click Re-check on the OpenCode card.

Next Steps

Once OpenCode is installed and at least one provider is configured, open CodeMantis and pick OpenCode from the agent picker (marked with an ACP badge) when you start a session.

• Using OpenCode — Run a session, configure providers, and use Plan mode.
• Choosing Your Coding Agent — When to pick Claude, Codex, or OpenCode.
• Per-Task Agent Routing — Route main chat, SpecWriter, Help, and the Assistant panel to different agents.
• OpenCode Not Found — Troubleshoot detection issues.

For the full OpenCode documentation, visit the official OpenCode project.