How to Use OpenCode

OpenCode is an open-source terminal AI coding agent from the sst team. It runs in your shell, reads and edits files in your repo, runs commands, and brings its own TUI so you can keep coding without leaving the terminal.

What OpenCode actually is

OpenCode is a standalone, model-agnostic agent. It is not a VS Code extension and it is not a wrapper around someone else’s CLI. You point it at a directory, give it a task, and it plans, edits files, and executes shell commands inside that working tree. It supports Anthropic, OpenAI, Google, and local providers via their own keys or a gateway, so you pay the model vendor directly instead of a middleman.

Installing

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

# or via npm
npm install -g opencode-ai

After install, run opencode auth login and pick a provider. Anthropic and OpenRouter are the two most common paths; OpenRouter is useful if you want to flip between Claude, GPT, and Gemini without juggling three billing dashboards.

A first session

cd ~/code/my-app
opencode

That drops you into the TUI. Type your request in plain English — “add a health check endpoint at /healthz that returns 200 and the git sha” — and OpenCode will read relevant files, propose edits, and ask before running shell commands. Use /model to switch models mid-session and /init to have it generate an AGENTS.md that captures your build/test commands so future sessions boot faster.

Configuration that matters

Drop an opencode.json at the repo root to pin the default model, register MCP servers, and declare allowed shell commands. The biggest win is the permission config: set permission.edit to ask for a new codebase and allow once you trust the loop. Also add an AGENTS.md — OpenCode reads it automatically and it is how you teach the agent “always run pnpm typecheck before you claim you’re done.”

Where OpenCode shines

Multi-file refactors where you want the agent to grep the repo, edit five files, run tests, and iterate until green — all without leaving tmux. The TUI’s diff view is genuinely good, and because it is provider-agnostic you can keep your existing API keys. It also plays well with SSH sessions on a remote dev box, which is something most editor-bound agents handle poorly.

When not to reach for it

If your workflow is “autocomplete while I type” you want Copilot or Cursor Tab, not OpenCode. And if you hate the idea of an agent running shell commands on your machine, set permissions to ask everywhere or pick a reviewer-style tool instead. Finally, bills get real — a single big refactor can burn a few dollars of Claude Sonnet tokens, so keep an eye on the provider dashboard for the first week.