Skill: OpenCode

Part of AI Engineering Lab · Developed by Zorost Intelligence AI Lab · zorost.com

1. What it is

OpenCode is an open-source, terminal-first AI coding agent from SST (the team behind the SST framework and OpenNext). It is deliberately model-agnostic and provider-agnostic: point it at Anthropic, OpenAI, OpenRouter, Ollama, LM Studio, or any OpenAI-compatible endpoint and it works the same way.

It ships a full TUI (session list, slash commands, diff review) plus desktop, web, and IDE-extension surfaces, but the terminal is the heart of it. Because it is free and speaks to any endpoint, it's the natural first harness for this program: test prompts against a local model for free, then flip one config line to a hosted model.

• Builder: SST
• Site / docs: https://opencode.ai · https://opencode.ai/docs/

2. Install

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

# or via npm
npm i -g opencode-ai

opencode            # launch the TUI

Auth is separate: opencode auth login stores credentials for a provider, or you supply keys per provider in config / environment variables.

3. Core workflow (the TUI)

Run opencode inside your repo and you get an interactive session:

> Build the ETA CLI from SPEC.md. Read SPEC.md first, then implement and run the tests.

The agent edits files and shows a diff; you review/accept; it iterates until your tests or approval pass. Useful keys/commands:

Input	What it does
/help	List commands and keybinds
/new	Start a new session
/sessions	List and switch sessions
/share	Share a session for collaboration
/models	Show available models and switch
Tab / arrows	Navigate the diff; accept/reject hunks
Esc	Interrupt the running agent

Sessions are first-class: each is a persisted conversation you can return to, branch from, or share, so a long Week 13 loop isn't lost when you close the terminal. The client/server split means the core keeps running headless while any surface (TUI, web, IDE) attaches, so you can leave a session running and reconnect from another terminal.

4. Config: opencode.json

Config lives in opencode.json at the project root, or globally at ~/.config/opencode/opencode.json. A provider map holds named providers (baseURL, apiKey, models), and model sets the default.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "npm": "@ai-sdk/openrouter",
      "options": { "baseURL": "https://openrouter.ai/api/v1" }
    },
    "ollama": {
      "npm": "ollama-ai-provider",
      "options": { "baseURL": "http://localhost:11434/v1" }
    }
  },
  "model": "openrouter/anthropic/claude-sonnet-4"
}

• Set the model by slug: "anthropic/claude-sonnet-4", "openrouter/... ", or a local "ollama/llama3.2".
• API keys can come from opencode auth login or environment variables per provider (e.g. OPENROUTER_API_KEY, ANTHROPIC_API_KEY). Reference the env var rather than pasting the secret into JSON.
• Because it targets any OpenAI-compatible endpoint, the same config works for OpenRouter, Ollama, LM Studio, and local servers.

A richer example, two providers plus a local model with an explicit baseURL:

{
  "provider": {
    "anthropic": { "npm": "@ai-sdk/anthropic", "options": { "apiKey": "env:ANTHROPIC_API_KEY" } },
    "openrouter": { "npm": "@ai-sdk/openrouter", "options": { "baseURL": "https://openrouter.ai/api/v1" } },
    "lmstudio": { "npm": "openai", "options": { "baseURL": "http://localhost:1234/v1" } }
  },
  "model": "openrouter/deepseek/deepseek-chat"
}

5. Rules: AGENTS.md

OpenCode auto-loads AGENTS.md as persistent instructions: the project file (./AGENTS.md) and a global ~/.config/opencode/AGENTS.md for cross-project defaults. This is the single highest-leverage config in the whole tool, put build commands, conventions, and "don't touch these files" there.

# AGENTS.md

## Commands
- Install: `pip install -e .`
- Run tests: `pytest -q`
- Lint: `ruff check src`

## Conventions
- Python 3.11+, type hints on public functions.

## Never touch
- `data/raw/`, `secrets/`, `.env`, `*.key`

6. Providers (incl. OpenRouter)

OpenCode's provider map makes multi-provider work trivial:

• Anthropic / OpenAI: native providers with opencode auth login.
• OpenRouter: one provider entry pointing at https://openrouter.ai/api/v1, then any model by slug (see the openrouter skill). This is the fastest way to try many models.
• Ollama / LM Studio: point baseURL at http://localhost:11434/v1 (or :1234/v1) to run a model locally for free.
• Any OpenAI-compatible server: vLLM, SGLang, TGI, or your own endpoint.

Power move: test a prompt for free on a local/Ollama model, then flip model to a hosted slug, zero code changes.

7. When OpenCode shines

• Model-agnostic exploration: you want to A/B the same task across Anthropic, DeepSeek, a local model, and OpenRouter without touching your code.
• Terminal-native, git-centric work: you live in the shell and want a fast TUI, not an editor.
• Headless / client-server: the core can run headless with any surface attached, so it slots into scripts and CI.
• Teams: share a session for collaboration; commit AGENTS.md + opencode.json so everyone gets the same setup.

Choose OpenCode when you want an open, flexible, terminal-first agent you can point at any model; choose Claude Code when you want Anthropic's polished defaults; choose DSH when you want plugin-level composition and a full trace.

8. Cost & safety

• Cost. Free, open source (MIT), you pay only your model provider. Control cost by model choice (local/:free for plumbing, hosted for real work) and by keeping AGENTS.md/context tight.
• Safety. OpenCode has a permission/policy system, configure which tools need approval. Run on a branch, keep secrets in env vars (never in prompts), and add a "never touch" list to AGENTS.md. Review diffs before accepting.

9. Common failures

Symptom	Likely cause	Fix
opencode: command not found	Install path issue	Reinstall via the curl script, or use npm i -g opencode-ai.
"No provider configured"	Missing provider/model in opencode.json	Add the provider map + model (see §4).
Auth errors on first call	No credentials for that provider	opencode auth login or set the provider's API key env var.
Agent ignores repo conventions	No AGENTS.md	Add one at the repo root; restart the session.
Local model won't connect	Wrong baseURL / Ollama not running	Start Ollama; confirm http://localhost:11434/v1 responds.
Model slug 404s	Provider renamed/deprecated the slug	Check opencode.ai/models or OpenRouter; update model.
Diff applies to wrong files	Task too vague	Narrow the task; point at specific paths.

10. Sources

• OpenCode site: https://opencode.ai
• OpenCode docs: https://opencode.ai/docs/
• OpenCode config reference: https://opencode.ai/docs/config/
• OpenRouter (for the OpenRouter provider): https://openrouter.ai/docs/llms.txt

Config keys and provider schemas evolve; re-check the docs before quoting.

---

© 2026 Zorost Intelligence LLC · https://zorost.com