OpenCode: First Session with the Coding Agent

OpenCode is an open-source coding agent that lives in your terminal: it reads your repo, edits files, and runs commands, driven by whatever model you point it at. Unlike Claude Code it is provider-agnostic, so the same agent runs on a cloud API or a local model. Everything below follows the official docs.

1. Install the CLI

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

That script puts opencode on your PATH; a package manager works too, via npm install -g opencode-ai. Confirm with opencode --help.

2. Start it in your project

cd /path/to/project
opencode

Running opencode opens the terminal UI rooted at your repo; run /init once so the agent scans the code and writes an AGENTS.md context file you commit to Git.

3. Connect a provider or local model

/connect

/connect walks you through signing in and pasting an API key (stored in ~/.local/share/opencode/auth.json); /models then lists the 75+ providers OpenCode supports via models.dev. To run fully local against Ollama, add it as a custom provider in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama2": { "name": "Llama 2" } }
    }
  }
}

Point baseURL at your Ollama server and list each pulled model; if tool calls misbehave, raise Ollama’s num_ctx to 16k-32k.

4. Give the agent a task

With a model selected, type a request in plain language, such as “add a /health endpoint and a test for it”. OpenCode proposes file edits and shell commands and waits for your approval before acting, the same review-first loop as terminal agents like Aider.

5. How it compares to Claude Code and Cursor

Claude Code is a terminal agent tied to Anthropic’s models; Cursor is a GUI editor with an agent built in. OpenCode keeps the terminal workflow but stays open-source and model-agnostic, so you can swap a frontier API for a local model in place. For the editor-versus-terminal trade-off, see Claude Code vs Cursor.

If it fails

• opencode: command not found The install location is not on your PATH. Reopen the shell, or put npm’s global bin folder on your PATH.
• No models listed or an authentication error You have not connected a provider. Run /connect for an API key, or for Ollama confirm ollama serve is running and the model pulled.
• The agent ignores tools or loops with a local model Small models drop tool calls. Pick a tool-capable model and raise num_ctx (start at 16k).

Next: Aider first steps · Codex CLI first steps · Claude Code vs Cursor.