OpenCode

What it is

OpenCode is an open source AI coding agent. You use it in a full-screen terminal interface, in a desktop app that the README marks BETA, or in a web app. You describe a change in plain words. The agent searches and reads your code, edits files and runs commands, and asks first where your rules say so. By default one shared background server owns the sessions, and every local client connects to it. This listing holds Mindket’s setup notes for it, written from the maker’s README and docs.

1. You describe a task in plain words
2. The agent reads, searches, edits and runs commands
3. Your permission rules allow, ask or deny each action
4. /undo can roll the files back, inside a Git repository
5. One shared server keeps the session for every client

Who it suits

Developers who want a coding agent in the terminal that works with the model they already have. That can be a provider key, a ChatGPT Plus or Pro sign-in, GitHub Copilot with Copilot Chat access, OpenCode’s free models, or a local model from Ollama, LM Studio or vLLM. It also suits people who keep a project’s rules in files: an AGENTS.md for conventions, agents, commands and skills as Markdown, and permission rules in opencode.jsonc. Admins can set policies that a repository cannot undo.

Skip it if you need something settled. The desktop app is marked BETA, and OpenCode 2 changes plugins, the server API and the terminal settings from OpenCode 1.

Where to use it

OpenCode runs in these places.

• Terminal: the command line, from an install script, a package manager, or a standalone download for macOS, Windows and Linux
• Desktop app (BETA): macOS and Windows installers, and .deb, .rpm and AppImage files for Linux
• Browser: opencode pair prints a link that opens the web interface
• Another machine: opencode serve on the host, a client started with --server, or an SSH port forward
• Docker: the Intro page names versioned image tags but gives no run command

The Intro page says OpenCode has built-in support for many LLM providers. Setup covers provider keys, a ChatGPT sign-in, GitHub Copilot, Ollama, LM Studio, vLLM and a custom OpenAI-compatible endpoint.

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with every command copied from the OpenCode docs. The main route is one install line, then a model.

1. Install the command line. On macOS or Linux, use the curl line below or a package manager line from the notes. On Windows, download the standalone Windows zip (ARM64, x64 or x64 baseline) listed in the notes.
2. Run opencode in your project folder. It opens the full-screen terminal interface.
3. Type /connect and pick a provider. Finish its sign-in, then type /models and choose a model.
4. Set rules for shell commands. By default the agent may run them without asking, so add the ask rule from the notes before real work.

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

The README labels the curl line “YOLO”. The line downloads a script and runs it at once with bash. It installs OpenCode to $HOME/.opencode/bin. Package managers are the other route, for example brew install anomalyco/tap/opencode-v2 or npm install -g @opencode/cli.

How to use it

Ask for the outcome and let the agent choose its tools. The Tools page’s example prompt is below.

Find where request timeouts are configured, change the default to 30 seconds, and run the relevant existing tests.

The TUI page says Shift+Tab cycles agents, and Ctrl+X then A, or /agents, picks one. There are two built-in primary agents. Build has full access. Plan is read-only and denies file edits by default. The README adds that plan asks before shell commands, but the Permissions page’s defaults give plan no shell rule, so add one yourself.

Example

You want a second look at your changes, and you do not want the agent to edit anything. You saved the Agents page’s reviewer, shown below, as .opencode/agents/reviewer.md. You ask your main agent:

Use the reviewer subagent to review my current changes.

The reviewer runs in a child session with fresh context and its own permissions. It cannot edit files or run shell commands, so it reads your changes. Its prompt tells it to list findings in severity order, with file and line references.

This is the reviewer file from the Agents page. Change the model line to a model you have connected.

---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Review the current changes. List findings in severity order with file and line references.

The parent agent’s subagent rules decide which subagents it may launch.

For newcomers and experts

If you are new. A coding agent is more than a chat box. It reads your project, edits files and runs commands, and it does that through tools. In OpenCode the default policy allows every tool except reading .env files, which ask first. Start in a Git repository, so /undo can restore files. Try the plan agent on a project you do not know yet. Run /models before your first prompt to see what you can use. The Intro page also points to Boot.dev’s course on AI coding with OpenCode, which Boot.dev created in consultation with the OpenCode team. It says the course information is free to read and watch, though some interactive features may require payment.

For experts. Most of what OpenCode does is set by files and a server.

• One server, many clients: by default one shared background server owns sessions, configuration, permissions and tool execution. opencode --standalone gives one run a private server, and opencode serve runs it in the foreground for systemd or Docker
• Config layers: global, project and system opencode.json(c) files merge. A project file overrides the global one, and the system file overrides all of them. Policies from global and project files run in the reverse order, so broader configuration outranks a project
• Models: provider/model with an optional #variant. A custom OpenAI-compatible provider goes under providers, with its package, base URL and models
• MCP and Code Mode: servers go under mcp.servers. Code Mode is the default and groups tools by server name, and "codemode": false keeps a server’s tools on the native tool list
• Skills: OpenCode also reads .claude/skills and .agents/skills, and an agent loads a skill by its exact ID
• Plugins: package plugins install with opencode plugin add. Plugins written for OpenCode 1 do not run in version 2

Good to know

OpenCode acts on your machine, and a few of its paths reach out.

• Acts without asking: the default policy allows every action except reading .env files, and the shell tool has your user’s filesystem, process and network authority
• Outside the project: version 2 allows access outside the project by default, where version 1 asked. A rule that sets external_directory to ask brings the prompt back
• Your model provider sees your work: prompts and file contents go to the provider whose model you use, which is OpenCode’s own opencode provider when you use its free models. For OpenCode Go, the Go page lists training and retention terms per model, and blocks paid endpoints that train on request data by default
• Keys: saved API keys and OAuth tokens live in the server’s SQLite database. In a config file, write {env:NAME} in place of a key
• Snapshots: OpenCode captures snapshots around every model step by default, for /undo, in a Git object database under its data folder. They can contain the complete contents of tracked and eligible untracked files, so treat that folder as sensitive, and keep Git commits for work that matters. "snapshots": false stops future capture but does not delete stored snapshots
• Remote access: the first time, opencode pair --remote asks before it exposes your server to the internet. Once accepted, later runs skip the prompt, even after remote access was turned off with opencode service set remote false. The Web page says traffic is end-to-end encrypted and access needs your server password
• Heap snapshots: one written by opencode debug heap-dump, or by the desktop app’s command palette, can contain prompts, file contents and credentials. Do not share it publicly
• Usage data: the pages behind these notes do not say whether OpenCode sends any, so Mindket cannot tell you
• Paid options: OpenCode Console and OpenCode Go are optional, and the Go page says you do not need Go to use OpenCode
• Removal: opencode uninstall --dry-run previews it. Session data, configuration and state are never removed
• Name: the README asks any project that uses “opencode” in its name to say it is not built by the OpenCode team. These notes are not made or endorsed by that team
• License: MIT. The LICENSE file reads “Copyright (c) 2025 opencode”