Guide

How to install OpenCode (macOS & Windows)

To install OpenCode, run the official script — curl -fsSL https://opencode.ai/install | bash — on macOS, Linux, or Windows Subsystem for Linux, and you have a working opencode command in under a minute. OpenCode is the open-source, terminal-native AI coding agent maintained by Anomaly (the team formerly known as SST); it reads your repo, runs commands, and edits files, while letting you point it at almost any model provider you choose. This guide walks the whole path: install on both platforms, pick a provider, run your first prompt, verify it works, and float it in an overlay so you don't have to babysit the terminal.

None of the commands below are invented — they're the ones the project documents. Package names and config keys do shift between releases, so when something doesn't match what you see on screen, the official OpenCode docs are the source of truth, not a copied snippet.

Install OpenCode on macOS & Windows

OpenCode ships as a single binary, so install is quick on every platform. The universal install script detects your OS and architecture, downloads the right build, and puts it on your PATH:

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

That one line works on macOS, Linux, and WSL. If you prefer a package manager, you have options:

• macOS (Homebrew): brew install anomalyco/tap/opencode uses the project's own tap, which tracks releases closely. The community formula brew install opencode exists too but tends to lag.
• npm (any platform): npm install -g opencode-ai. Note the package is opencode-ai, not opencode — that naming trips people up. The command you run afterward is still just opencode.
• Windows: scoop install opencode or choco install opencode both work on native Windows. That said, the project recommends running OpenCode inside WSL for the best compatibility — once you're in a WSL shell, the curl | bash line above is the simplest route.

Whatever method you use, confirm the install landed before going further. If opencode isn't found after a global npm install, your npm global bin directory isn't on PATH — run npm prefix -g and add that /bin to your shell profile. For the always-current matrix of install methods, the download page is canonical.

Pick a model provider

OpenCode is deliberately model-agnostic: it drives 75+ providers and is free and MIT-licensed, so the only thing you pay for is the model behind it. We unpack that design in what is OpenCode. To wire one up interactively, run:

opencode auth login

That walks you through provider selection and stores credentials locally (under ~/.local/share/opencode/auth.json). You can target a provider directly with opencode auth login --provider anthropic, and list what's connected with opencode auth list.

If you'd rather keep configuration in version-friendly text, drop an opencode.json at your project root. The schema lives at a public URL, so editors give you autocomplete. Here's a minimal Anthropic config that sets a default model and reads the key from your environment rather than hard-coding it:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

The {env:ANTHROPIC_API_KEY} syntax pulls the secret from an environment variable so it never sits in the file; OpenCode also supports a {file:path} form if you keep keys in a separate file. Set the variable first, for example export ANTHROPIC_API_KEY="sk-ant-...", and treat it like a password — never commit it.

The honest catch with Claude. You'll see community guides that log a Claude Pro or Max subscription into OpenCode via OAuth. As of early 2026, Anthropic's OAuth terms reserve those subscription tokens for its own official clients, so pointing a third-party agent at a Pro/Max login is a gray area that can break whenever Anthropic adjusts its OAuth infrastructure. The clean, supported way to run Claude inside OpenCode is a pay-as-you-go Anthropic API key (billed per token), not a subscription. If you want to avoid that decision entirely, the hosted route below sidesteps it. For a fuller comparison of the two agents, see OpenCode vs Claude Code.

Your first prompt

OpenCode reads the directory it's launched from, so always start it at the repo root:

cd ~/your-project
opencode

On first launch in a new repo, run /init — it analyzes the project and writes an AGENTS.md the agent uses for context on later runs. Then type a task in plain English: "add a health-check endpoint and a test for it," say. OpenCode gathers context, proposes a change, runs something, and checks the result — the same agent loop as Claude Code or the Codex CLI. Start conservative on autonomy: let it propose a small change, watch what it edits and which commands it wants to run, and loosen the leash once you trust it.

Verify it works

Three quick checks confirm a clean setup before you lean on it:

• Binary is on PATH: a bare opencode should launch the TUI rather than printing "command not found." If you want the build number, opencode --version prints it (and the docs list the current flags if that ever changes).
• Provider is connected: opencode auth list should show your provider with a valid credential. No entry means auth login didn't finish.
• A real round-trip: ask it something tiny that needs the model — "summarize this repo in two sentences." A coherent answer means the key, model id, and network path all work. An auth error here almost always points back to a missing or mistyped ANTHROPIC_API_KEY, not the install.

Run it in an overlay

Once OpenCode works, the next friction is practical: it's a terminal program, and a terminal is easy to lose behind your editor, your browser, or a game. That's the gap an overlay fills. An overlay is a thin, always-on-top window that floats your agent over whatever's on screen — it works over borderless-fullscreen apps specifically, so the agent stays visible without you alt-tabbing away. We go deeper on the setup in running OpenCode in an overlay, and the same pattern lets you run an agent while gaming.

OpenCode's client-server design makes it an especially good fit: the agent runs in a backend the overlay simply attaches to, so the heavy process keeps going even when the window is hidden. You glance over when a notification fires, deal with a decision, and glance back. The overlay is a frontend, not the agent — it renders your real CLI and pings you on the events that matter.

Or skip setup with hosted Grindy

If providers and API keys are more setup than you want, Grindy is the zero-config option. It's Backgrind's managed engine, built on OpenCode: you pick the grindy model and get a real Claude engine behind the scenes — grindy-1 on Claude Haiku 4.5, grindy-1-pro on Claude Sonnet 4.6 — with nothing to install and no provider key to manage. The OAuth gray area above simply doesn't apply, because you're not bringing your own subscription. If you'd still rather run OpenCode yourself with your own keys, nothing stops you; Grindy just removes the setup for people who don't want to touch providers at all. Deciding which agent to standardize on? Our best AI coding agent in 2026 rundown lays out the trade-offs.

Frequently asked questions

Where Backgrind fits

Backgrind isn't an agent or a model — it's the always-on-top overlay and notification layer that sits in front of the agent you already run. Install OpenCode with the commands above, and Backgrind becomes just another calm client over your real CLI: it floats the terminal over any borderless-fullscreen app and pings you only when OpenCode needs a decision or finishes. If you'd rather skip the provider setup entirely, Grindy gives you a hosted OpenCode plus a Claude engine with nothing to configure. Either way, you keep your own login and history — and you can feel the notification loop in the live demo.