# How to use opencode: a step-by-step guide URL: https://agentvera.dev/en/blog/how-to-use-opencode/ · Published: 2026-10-27 How to use opencode: install it, connect a provider, pick a model, switch between Build and Plan, and set up opencode.json, AGENTS.md, MCP servers and commands. **In short:** - Install opencode with the official script or npm, run opencode in a project, connect a provider with /connect and pick a model with /models; any provider works, local models included. - Tab switches between the Build agent, which edits and runs commands, and the Plan agent, which can’t edit your code and is for thinking a change through first. - Settings live in opencode.json (global and per project), project rules in AGENTS.md; MCP servers go under the mcp key and custom commands in .opencode/commands/. 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](/en/glossary/coding-agent/ "What 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 | Platform | Command | | --- | --- | | macOS, Linux | `curl -fsSL https://opencode.ai/install \| bash` | | Any platform with Node.js | `npm install -g opencode-ai` | | macOS, Linux (Homebrew, version 1) | `brew install anomalyco/tap/opencode` | | Windows | `choco install opencode` or `scoop 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: ```bash 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`: ```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](/en/blog/local-llm-coding-agent/ "Local LLM coding agent"). ## 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. | Command | Shortcut | What it does | | --- | --- | --- | | `/connect` | | Add a provider | | `/models` | `ctrl+x m` | Pick a model | | `/new` | `ctrl+x n` | Start a new session | | `/sessions` | `ctrl+x l` | Open an earlier session | | `/compact` | `ctrl+x c` | Summarize the session to free up context | | `/undo` | `ctrl+x u` | Undo the last message and its file changes | | `/redo` | `ctrl+x r` | Redo what you undid | | `/editor` | `ctrl+x e` | Write a long prompt in your `$EDITOR` | | `/export` | `ctrl+x x` | Export the conversation as Markdown | | `/init` | | Create or update `AGENTS.md` | | `/exit` | `ctrl+x q` | Quit | `/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 ` 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](/en/glossary/subagent/ "What is a 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: ```json { "$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: ```json { "$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. ```markdown # 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](/en/blog/claude-md-agents-md/ "How to write CLAUDE.md and AGENTS.md") covers what belongs in the file. ## Step 7: MCP servers [MCP servers](/en/blog/what-is-mcp-server/ "What is an MCP server") 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: ```json { "$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 ` signs in by hand. `opencode mcp debug ` 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: ```markdown --- 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](/en/agents/opencode/ "opencode in AgentVera") 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](/en/features/mcp-manager/ "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](/en/features/workspace/ "Workspace") grid, each agent in its own [git worktree](/en/glossary/git-worktree/ "What is a git worktree"), so they don’t step on each other’s files. - **Review and flows.** opencode agents work with [automatic code review](/en/features/code-review/ "Automatic code review"), and in [flows](/en/features/flows/ "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](/en/download/ "Download AgentVera") to try it. If your team also runs Claude in CI, [Claude Code GitHub Actions](/en/blog/claude-code-github-actions/ "Claude Code GitHub Actions") covers that side, and [How to use Codex CLI](/en/blog/how-to-use-codex-cli/ "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. ## Frequently asked questions **Is opencode free?** The CLI is free to install. You pay for the models you use through your provider: an API key billed per token, a subscription you already have such as GitHub Copilot or ChatGPT Plus/Pro, or OpenCode Zen. Local models through Ollama cost nothing beyond your own hardware. **Which models can opencode use?** Any provider it supports: Anthropic, OpenAI, Google, GitHub Copilot, OpenRouter, OpenCode Zen and many more, plus local models through an OpenAI-compatible server such as Ollama. Run opencode models to list what your connected providers offer. **What is the difference between the Build and Plan agents?** Build is the default and has all tools, so it edits files and runs commands. Plan cannot edit your code; it may only write Markdown plans in .opencode/plans/. Use Plan to think a change through, then press Tab to switch to Build and carry it out. **Does opencode read CLAUDE.md?** Yes, as a fallback. If a project has no AGENTS.md, opencode reads CLAUDE.md, and it also falls back to ~/.claude/CLAUDE.md for global rules. Set OPENCODE_DISABLE_CLAUDE_CODE=1 to turn the Claude Code fallbacks off. **Where does opencode store its settings and logins?** Global settings are in ~/.config/opencode/opencode.json and project settings in opencode.json at the project root; the two are merged. Provider credentials from /connect are stored in ~/.local/share/opencode/auth.json. --- **About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/