How to use opencode: a step-by-step guide

To use opencode, install it with one command, run opencode in a project folder, connect a model provider with /connect, pick a model with /models, and describe what you want. The default Build agent reads your code, edits files and runs commands. Press Tab to switch to the Plan agent when you want to think a change through without touching any code.

That’s the core loop. This guide covers the rest: providers and local models, the TUI commands you’ll use every day, the two built-in agents, opencode.json, AGENTS.md, MCP servers, custom commands, and running opencode next to other agents. Everything here follows opencode’s official documentation as of October 2026.

What opencode is

opencode is a coding agent for the terminal that isn’t tied to one AI company. Claude Code uses Anthropic models and Codex uses OpenAI models. opencode is built on the AI SDK and Models.dev, so it works with dozens of providers and with local models. You can use one model for planning and another for building, and change provider without learning a new tool.

A note on versions: opencode 2 has been released, with its own docs. Both versions install a command called opencode, and you can’t keep both under that name. This guide follows version 1, which is what the npm package opencode-ai installs. Most of it carries over to version 2. If you installed through Homebrew’s core formula or Arch’s main repository, you probably have version 2, so check the matching docs.

Step 1: install opencode

bun, pnpm and yarn global add opencode-ai work too. On Windows the docs recommend running opencode inside WSL for the best experience. A modern terminal such as WezTerm, Alacritty, Ghostty or Kitty renders the TUI best.

opencode never updates itself in the background. Inside a session, /update installs a newer version 1 release, or offers the upgrade to version 2 when you are already on the latest version 1. From the shell, opencode upgrade does the same job.

Step 2: connect a provider and pick a model

Move into a project and start opencode:

cd my-project
opencode

Then run /connect and choose a provider. You can do the same from the shell with opencode auth login. Credentials are saved in ~/.local/share/opencode/auth.json, and opencode auth list shows what is connected. opencode also picks up API keys from environment variables and from a .env file in the project.

Some common choices:

• OpenCode Zen: a curated list of models the opencode team has tested with the agent. Sign in at opencode.ai/auth, add billing, copy the key and paste it into /connect. The docs suggest it for new users.
• Anthropic: paste an API key from the Claude Console. Signing in with a Claude Pro or Max subscription isn’t offered. Anthropic doesn’t allow third-party tools to use those plans this way, and opencode stopped shipping the plugins that did.
• OpenAI: choose “ChatGPT Plus/Pro” to sign in through the browser, or enter an API key manually.
• GitHub Copilot: sign in with a device code at github.com/login/device. Some models need a higher Copilot plan.
• Local models: add a custom provider pointing at an OpenAI-compatible server (see below).

Once a provider is connected, /models (or ctrl+x m) opens the model picker. From the shell, opencode models lists every model your providers offer, and opencode models anthropic lists one provider’s models. Models are written as provider/model, for example anthropic/claude-sonnet-5-5. Many models have variants, such as higher reasoning effort, and ctrl+t cycles through them.

Local models with Ollama

A local model is 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"
        }
      }
    }
  }
}

If tool calls fail with a local model, the docs suggest raising Ollama’s num_ctx to around 16k–32k. A small context window is the usual cause. For choosing a local model in the first place, see local LLM coding agents.

Step 3: TUI basics

The opencode screen is a chat with your project. The handful of things you’ll use constantly:

• @ fuzzy-searches files and adds them to your message.
• ! at the start of a line runs a shell command, for example !npm test, and puts the output in the conversation.
• ctrl+x is the leader key. Most shortcuts are ctrl+x followed by a letter.
• You can drag images into the terminal to include them.

/undo relies on Git to roll back file changes, so the project should be a Git repository. To continue where you left off from the shell, opencode -c reopens the last session and opencode -s <id> opens a specific one. For scripts and CI, opencode run "your prompt" runs a single task without the TUI.

Step 4: the Build and Plan agents

opencode has two primary agents, and Tab switches between them:

• Build is the default. It has every tool enabled: it edits files, runs shell commands and calls MCP servers.
• Plan is restricted. It can’t edit your code; the only files it may write are Markdown plans in .opencode/plans/. It can ask you clarifying questions.

A good habit for anything non-trivial is to start in Plan, agree on an approach, then press Tab and tell Build to carry it out. There are also two subagents you call with @: @general for multi-step research and changes, and @explore for fast read-only searches through the codebase. Each runs in a child session. ctrl+x then the down arrow enters it, and the up arrow goes back to the parent. The subagent glossary entry explains why this saves context.

One pitfall: Plan doesn’t limit bash by itself. Shell commands follow your permission settings. Also, a top-level "edit": "allow" in your config applies to Plan too, because later matching rules win. If you want Plan locked down, set its permissions directly:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

You can create your own agents with opencode agent create, or as Markdown files in .opencode/agents/ (per project) or ~/.config/opencode/agents/ (global). The file name becomes the agent’s name. Frontmatter sets its description, mode (primary or subagent), model and permission.

Step 5: the config file

opencode reads opencode.json (or opencode.jsonc, which allows comments). There are two common places:

• Global: ~/.config/opencode/opencode.json, for your defaults.
• Project: opencode.json in the project root, committed with the code.

The files are merged, not replaced, and project settings win where they overlap. A practical project config:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "npm test *": "allow"
    }
  },
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

• model is the default model. small_model is used for light jobs such as session titles.
• permission takes allow, ask or deny per tool, with patterns for bash. The last matching pattern wins, so put "*" first.
• instructions adds more rule files on top of AGENTS.md. Globs and URLs work.

Values can come from the environment with {env:VAR} or from a file with {file:path}, so keys never need to sit in the config. By default most actions are allowed. Reading .env files and touching folders outside the project ask first. opencode --auto approves everything that isn’t explicitly denied, so use it only somewhere you would be comfortable letting the agent run unattended.

TUI settings such as the theme and keybinds live in a separate tui.json.

Step 6: AGENTS.md

AGENTS.md holds your project rules: how to build, test and lint, the conventions to follow, the folders to stay out of. Run /init and opencode scans the project and writes one for you. Read it, trim it and commit it.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- API handlers live in src/api/; one file per route.
- Never edit files in src/generated/.

Global rules for every project go in ~/.config/opencode/AGENTS.md. If you are coming from Claude Code, opencode falls back to a project CLAUDE.md when there is no AGENTS.md, and reads ~/.claude/CLAUDE.md and ~/.claude/skills/ too. Set OPENCODE_DISABLE_CLAUDE_CODE=1 to turn that off. How to write CLAUDE.md and AGENTS.md covers what belongs in the file.

Step 7: MCP servers

MCP servers give opencode new tools: a browser, an issue tracker, documentation search. They go under the mcp key. A local server is a command opencode starts; a remote server is a URL:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    },
    "my-remote": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_MCP_TOKEN}"
      }
    }
  }
}

opencode mcp add adds a server interactively, and opencode mcp list shows what is configured and whether it connects. Remote servers that use OAuth sign in automatically, and opencode mcp auth <name> signs in by hand. opencode mcp debug <name> helps when a server won’t connect.

Every server adds its tools to the context of each request, and some large ones, such as the GitHub MCP server, add a lot. Turn on only the servers you need, and set "enabled": false to keep one configured but off.

Step 8: custom commands

A custom command is a prompt you’d otherwise retype. Put a Markdown file in .opencode/commands/ (per project) or ~/.config/opencode/commands/ (global); the file name becomes the command:

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Saved as .opencode/commands/test.md, this becomes /test. Commands accept arguments: $ARGUMENTS is everything after the command name, $1, $2 and so on are single arguments, !`git diff --staged` inserts a shell command’s output, and @src/file.ts includes a file. You can also define commands under the command key in opencode.json with a template. If a custom command has the same name as a built-in one, the built-in wins.

Common pitfalls

• “No provider” on first run. Nothing is connected yet. Run /connect.
• Edits in Plan mode. A global "edit": "allow" reaches Plan too. Set agent.plan.permission explicitly.
• /undo doesn’t revert files. The folder isn’t a Git repository.
• Two opencode versions fighting. Homebrew core installs version 2 and npm installs version 1 under the same command name. Check opencode --version and keep one.
• Slow, expensive sessions. Too many MCP servers, or a long session. Turn servers off and use /compact or /new.

Running opencode in AgentVera panes

One opencode session is easy to follow. Several agents at once, some on opencode, some on Claude Code or Codex, is where terminal tabs get in the way. AgentVera is a desktop app that runs these CLIs side by side in real terminals, using your own installs and logins. Its opencode support works like this:

• Your providers, your login. You sign in to providers inside opencode itself (/connect or opencode auth login), and every provider you connect, local models included, appears in AgentVera’s model list, grouped by provider. Model variants show up as effort options. If opencode isn’t installed, AgentVera installs it with npm i -g opencode-ai.
• One session per agent. Each opencode agent gets its own session, so duplicating an agent forks its conversation instead of sharing it. /compact works as usual.
• Your opencode.json stays untouched. The agent’s role, the MCP servers you added in AgentVera’s MCP manager and AgentVera’s browser are passed in as extra config and merged with yours.
• Panes and worktrees. Run opencode next to Claude Code in the workspace grid, each agent in its own git worktree, so they don’t step on each other’s files.
• Review and flows. opencode agents work with automatic code review, and in flows (Pro and Team) one agent’s answer can go to another automatically. For example, a cheap model plans and a stronger one builds.

The grid, worktrees, code review and the MCP manager are on the free plan. Download AgentVera to try it. If your team also runs Claude in CI, Claude Code GitHub Actions covers that side, and How to use Codex CLI is the same guide for OpenAI’s agent.

Wrapping up

To use opencode, install it, run opencode in a project, connect a provider with /connect and pick a model with /models. Use Plan to think and Build to change code, and switch between them with Tab. Put your defaults in opencode.json, your project rules in AGENTS.md, your tools under mcp, and your repeated prompts in .opencode/commands/. After that, opencode is mostly about choosing the right model for each job, and it lets you switch whenever you like.