TL;DR

• OpenCode is an open source AI coding agent built for the terminal, with desktop and IDE options too.

• It is MIT licensed, free to run, and model-agnostic. You pay only for the model tokens you use.

• It is a full agent harness (tool loop, LSP diagnostics, session management), not a chat wrapper.

• You can point it at 75+ providers, or at any OpenAI-compatible endpoint.

• Pointing OpenCode at Pioneer gives you access to Claude, GPT, Gemini, GLM, Llama 3, Qwen, DeepSeek models and more through one endpoint, with inference logs and a feedback loop that continuously fine-tunes your model against live production traffic.

The best coding model changes almost every month, and the agent you work in should let you follow that curve freely. OpenCode is built for exactly that. It is an open source coding agent that runs in your terminal and connects to almost any model from almost any provider, so the harness stays the same while the models underneath it change as fast as the field does.

This guide covers what OpenCode is, how to install and configure it, how it compares to Claude Code, Cursor, Aider, and Codex, and how to run inference through Pioneer so you can reach many models across providers behind a single endpoint.

What is OpenCode?

OpenCode is an open source AI coding agent that lives in your terminal. It reads and edits files, runs shell commands, and works through multi-step tasks on your codebase, all from a terminal UI. It is also available as a desktop app and an IDE extension, so you can use the same agent across surfaces.

It is built by Anomaly and the OpenCode community, and it is one of the most popular open source agents available, with over 170,000 GitHub stars and a large contributor base. The project is MIT licensed, which means the tool itself is free. Your only cost is the model inference you run through it.

The important distinction: OpenCode is a full agent harness, not a thin chat wrapper around an API. It has a real tool loop, Language Server Protocol (LSP) integration so the agent can read diagnostics as feedback, and session management for keeping separate pieces of work isolated. It runs on a client/server architecture, which is why the terminal, desktop, and IDE surfaces can all talk to the same engine.

Key features of OpenCode

• Model flexibility. OpenCode connects to 75+ providers out of the box through its Models.dev integration, and to any OpenAI-compatible endpoint beyond that. You can route different tasks to different models: a fast, cheap model for simple questions, a reasoning model for architecture, and a coding-specialized model for implementation.

• Plan mode and Build mode. Plan mode disables the agent's ability to change files and instead has it draft how it intends to implement something. Once the plan looks right, you switch to Build mode and it makes the changes. Toggle between them with the Tab key.

• Built-in tools. The agent reads, writes, and edits files, runs shell commands, and uses LSP diagnostics as feedback while it works. It completes real work in your repo instead of handing you snippets to paste.

• Multi-session support. Each session has its own context window, history, and model configuration, so you can keep a research session separate from an implementation session, or push several features forward at once without them bleeding into each other.

• Agents and subagents. You can define specialized agents with their own prompts, models, and tool access. OpenCode ships with two primary agents, Build and Plan, and you can add your own for the work you repeat.

• Custom commands. Store reusable prompts as Markdown files, per user or per project, with named argument placeholders. A prompt you retype ten times a day becomes a single command.

• MCP servers. OpenCode supports the Model Context Protocol, so you can connect external tools and services and expose them to the agent automatically, which means the agent can reach context that does not live in your repo.

• **AGENTS.md.** A project rules file that gives the agent persistent context about your architecture and conventions, so you stop re-explaining your project on every run.

• Themes, keybinds, formatters, permissions, and conversation sharing round out the customization surface.

How to set up OpenCode (step by step)

Prerequisites

OpenCode runs in any standard terminal, so the built-in Terminal or iTerm on macOS and most Linux terminals work out of the box. The only hard requirement is API keys for whatever models you plan to use. If you want the smoothest experience, the OpenCode team recommends a GPU-accelerated emulator like WezTerm, Ghostty, Alacritty, or Kitty, but that is optional. On Windows, we recommend running OpenCode inside Windows Subsystem for Linux (WSL) for the best compatibility.

Install OpenCode

The quickest path is the install script:

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

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

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

Or use a package manager. With Node.js:

npm install -g

npm install -g

npm install -g

With Homebrew on macOS and Linux (the tap gets the most up-to-date releases):

On Arch Linux:

sudo pacman -S opencode        # stable
paru -S opencode-bin           # latest from the AUR

sudo pacman -S opencode        # stable
paru -S opencode-bin           # latest from the AUR

sudo pacman -S opencode        # stable
paru -S opencode-bin           # latest from the AUR

On Windows, Scoop, Chocolatey, Mise, and Docker are all supported:

scoop install opencode
choco install opencode
mise use -g github:anomalyco/opencode
docker run -it --rm

scoop install opencode
choco install opencode
mise use -g github:anomalyco/opencode
docker run -it --rm

scoop install opencode
choco install opencode
mise use -g github:anomalyco/opencode
docker run -it --rm

Once OpenCode is installed, the next step is to connect a model provider. The fastest and most flexible option is Pioneer, so we start there.

How to run inference through Pioneer in OpenCode

Pioneer is an inference API that is drop-in compatible with your existing OpenAI or Anthropic client. Point OpenCode at it and you get access to a range of models across the Claude, GPT, and Gemini families through one endpoint, full inference logs, and a feedback loop that turns your production traffic into a sharper, cheaper model over time. Your weights and training data stay yours, and the optimization is included at no extra cost.

Point OpenCode at Pioneer

First, set the API key:

export PIONEER_API_KEY="<Your Pioneer API key>"

export PIONEER_API_KEY="<Your Pioneer API key>"

export PIONEER_API_KEY="<Your Pioneer API key>"

Run this one-time setup command that:

• fetches the live GET /v1/models catalog

• merges Pioneer into your global OpenCode config at ~/.config/opencode/opencode.json

• stores your API key in OpenCode’s credentials file at ~/.local/share/opencode/auth.json, and

• sets pioneer/auto as the default model.

: "${PIONEER_API_KEY:?Set PIONEER_API_KEY first}"

CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
CONFIG_FILE="$CONFIG_DIR/opencode.json"
CONFIG_TMP="$(mktemp)"
DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/opencode"
AUTH_FILE="$DATA_DIR/auth.json"
AUTH_TMP="$(mktemp)"

mkdir -p "$CONFIG_DIR" "$DATA_DIR"
[ -f "$CONFIG_FILE" ] || printf '{}\n' > "$CONFIG_FILE"
[ -f "$AUTH_FILE" ] || printf '{}\n' > "$AUTH_FILE"
cp "$CONFIG_FILE" "$CONFIG_FILE.bak.$(date +%Y%m%d%H%M%S)"
cp "$AUTH_FILE" "$AUTH_FILE.bak.$(date +%Y%m%d%H%M%S)"

curl -fsS "<https://api.pioneer.ai/v1/models>" \
  -H "Authorization: Bearer $PIONEER_API_KEY" \
  | jq --slurpfile current "$CONFIG_FILE" '
    def dedupe:
      reduce .[] as $item ([]; if index($item) then . else . + [$item] end);

    def catalog_models:
      (.models // []) as $models
      | if (($models | type) == "array" and ($models | length) > 0) then $models else (.data // []) end;

    def model_id:
      .slug // .id;

    def model_name:
      (.display_name // .name // .id // .slug)
      | sub(" (?<major>[0-9]+) (?<minor>[0-9]+)(?= |$)"; " \(.major).\(.minor)")
      | gsub("\\bGpt\\b"; "GPT")
      | gsub("\\bOss\\b"; "OSS");

    def reasoning_levels:
      [
        (.supported_reasoning_levels // .reasoning_levels // .supported_reasoning_efforts // [])
        | .[]
        | if type == "string" then . else (.effort // .id // .level // .name // empty) end
        | select(type == "string" and length > 0)
      ] | dedupe;

    def model_limits:
      (.max_input_tokens // .context_window // .contextWindow // null) as $context
      | (.max_output_tokens // .max_tokens // .maxTokens // null) as $output
      | if ($context != null and $output != null) then {context: $context, output: $output} else {} end;

    def opencode_model:
      (reasoning_levels) as $levels
      | ({name: model_name}
        + (if (model_limits | length) > 0 then {limit: model_limits} else {} end)
        + (if ($levels | length) > 0 then {
            reasoning: true,
            variants: ($levels | map({key: ., value: {reasoningEffort: .}}) | from_entries)
          } else {} end));

    ($current[0] // {}) + {
      "$schema": "<https://opencode.ai/config.json>",
      model: "pioneer/auto",
      provider: (($current[0].provider // {}) + {
        pioneer: {
          npm: "@ai-sdk/openai-compatible",
          name: "Pioneer",
          env: ["PIONEER_API_KEY"],
          options: {
            baseURL: "<https://api.pioneer.ai/v1>"
          },
          models: (
            {"auto": {"id": "pioneer/auto", "name": "Pioneer Auto"}}
            + (
              [catalog_models[]
                | select(.deprecated != true)
                | select(model_id != null)
                # Hide Claude Code discovery aliases so OpenCode does not show every model twice.
                | select(model_id | startswith("anthropic/pioneer/") | not)
                # Add the router once as the pioneer/auto model below, even if /v1/models includes it.
                | select(model_id != "pioneer/auto" and model_id != "auto")
                | {key: model_id, value: opencode_model}]
              | from_entries
            )
          )
        }
      })
    }' > "$CONFIG_TMP"

jq '. + {pioneer: {type: "api", key: env.PIONEER_API_KEY}}' "$AUTH_FILE" > "$AUTH_TMP"
chmod 600 "$AUTH_TMP"
mv "$CONFIG_TMP" "$CONFIG_FILE"
mv "$AUTH_TMP" "$AUTH_FILE"

: "${PIONEER_API_KEY:?Set PIONEER_API_KEY first}"

CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
CONFIG_FILE="$CONFIG_DIR/opencode.json"
CONFIG_TMP="$(mktemp)"
DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/opencode"
AUTH_FILE="$DATA_DIR/auth.json"
AUTH_TMP="$(mktemp)"

mkdir -p "$CONFIG_DIR" "$DATA_DIR"
[ -f "$CONFIG_FILE" ] || printf '{}\n' > "$CONFIG_FILE"
[ -f "$AUTH_FILE" ] || printf '{}\n' > "$AUTH_FILE"
cp "$CONFIG_FILE" "$CONFIG_FILE.bak.$(date +%Y%m%d%H%M%S)"
cp "$AUTH_FILE" "$AUTH_FILE.bak.$(date +%Y%m%d%H%M%S)"

curl -fsS "<https://api.pioneer.ai/v1/models>" \
  -H "Authorization: Bearer $PIONEER_API_KEY" \
  | jq --slurpfile current "$CONFIG_FILE" '
    def dedupe:
      reduce .[] as $item ([]; if index($item) then . else . + [$item] end);

    def catalog_models:
      (.models // []) as $models
      | if (($models | type) == "array" and ($models | length) > 0) then $models else (.data // []) end;

    def model_id:
      .slug // .id;

    def model_name:
      (.display_name // .name // .id // .slug)
      | sub(" (?<major>[0-9]+) (?<minor>[0-9]+)(?= |$)"; " \(.major).\(.minor)")
      | gsub("\\bGpt\\b"; "GPT")
      | gsub("\\bOss\\b"; "OSS");

    def reasoning_levels:
      [
        (.supported_reasoning_levels // .reasoning_levels // .supported_reasoning_efforts // [])
        | .[]
        | if type == "string" then . else (.effort // .id // .level // .name // empty) end
        | select(type == "string" and length > 0)
      ] | dedupe;

    def model_limits:
      (.max_input_tokens // .context_window // .contextWindow // null) as $context
      | (.max_output_tokens // .max_tokens // .maxTokens // null) as $output
      | if ($context != null and $output != null) then {context: $context, output: $output} else {} end;

    def opencode_model:
      (reasoning_levels) as $levels
      | ({name: model_name}
        + (if (model_limits | length) > 0 then {limit: model_limits} else {} end)
        + (if ($levels | length) > 0 then {
            reasoning: true,
            variants: ($levels | map({key: ., value: {reasoningEffort: .}}) | from_entries)
          } else {} end));

    ($current[0] // {}) + {
      "$schema": "<https://opencode.ai/config.json>",
      model: "pioneer/auto",
      provider: (($current[0].provider // {}) + {
        pioneer: {
          npm: "@ai-sdk/openai-compatible",
          name: "Pioneer",
          env: ["PIONEER_API_KEY"],
          options: {
            baseURL: "<https://api.pioneer.ai/v1>"
          },
          models: (
            {"auto": {"id": "pioneer/auto", "name": "Pioneer Auto"}}
            + (
              [catalog_models[]
                | select(.deprecated != true)
                | select(model_id != null)
                # Hide Claude Code discovery aliases so OpenCode does not show every model twice.
                | select(model_id | startswith("anthropic/pioneer/") | not)
                # Add the router once as the pioneer/auto model below, even if /v1/models includes it.
                | select(model_id != "pioneer/auto" and model_id != "auto")
                | {key: model_id, value: opencode_model}]
              | from_entries
            )
          )
        }
      })
    }' > "$CONFIG_TMP"

jq '. + {pioneer: {type: "api", key: env.PIONEER_API_KEY}}' "$AUTH_FILE" > "$AUTH_TMP"
chmod 600 "$AUTH_TMP"
mv "$CONFIG_TMP" "$CONFIG_FILE"
mv "$AUTH_TMP" "$AUTH_FILE"

: "${PIONEER_API_KEY:?Set PIONEER_API_KEY first}"

CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
CONFIG_FILE="$CONFIG_DIR/opencode.json"
CONFIG_TMP="$(mktemp)"
DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/opencode"
AUTH_FILE="$DATA_DIR/auth.json"
AUTH_TMP="$(mktemp)"

mkdir -p "$CONFIG_DIR" "$DATA_DIR"
[ -f "$CONFIG_FILE" ] || printf '{}\n' > "$CONFIG_FILE"
[ -f "$AUTH_FILE" ] || printf '{}\n' > "$AUTH_FILE"
cp "$CONFIG_FILE" "$CONFIG_FILE.bak.$(date +%Y%m%d%H%M%S)"
cp "$AUTH_FILE" "$AUTH_FILE.bak.$(date +%Y%m%d%H%M%S)"

curl -fsS "<https://api.pioneer.ai/v1/models>" \
  -H "Authorization: Bearer $PIONEER_API_KEY" \
  | jq --slurpfile current "$CONFIG_FILE" '
    def dedupe:
      reduce .[] as $item ([]; if index($item) then . else . + [$item] end);

    def catalog_models:
      (.models // []) as $models
      | if (($models | type) == "array" and ($models | length) > 0) then $models else (.data // []) end;

    def model_id:
      .slug // .id;

    def model_name:
      (.display_name // .name // .id // .slug)
      | sub(" (?<major>[0-9]+) (?<minor>[0-9]+)(?= |$)"; " \(.major).\(.minor)")
      | gsub("\\bGpt\\b"; "GPT")
      | gsub("\\bOss\\b"; "OSS");

    def reasoning_levels:
      [
        (.supported_reasoning_levels // .reasoning_levels // .supported_reasoning_efforts // [])
        | .[]
        | if type == "string" then . else (.effort // .id // .level // .name // empty) end
        | select(type == "string" and length > 0)
      ] | dedupe;

    def model_limits:
      (.max_input_tokens // .context_window // .contextWindow // null) as $context
      | (.max_output_tokens // .max_tokens // .maxTokens // null) as $output
      | if ($context != null and $output != null) then {context: $context, output: $output} else {} end;

    def opencode_model:
      (reasoning_levels) as $levels
      | ({name: model_name}
        + (if (model_limits | length) > 0 then {limit: model_limits} else {} end)
        + (if ($levels | length) > 0 then {
            reasoning: true,
            variants: ($levels | map({key: ., value: {reasoningEffort: .}}) | from_entries)
          } else {} end));

    ($current[0] // {}) + {
      "$schema": "<https://opencode.ai/config.json>",
      model: "pioneer/auto",
      provider: (($current[0].provider // {}) + {
        pioneer: {
          npm: "@ai-sdk/openai-compatible",
          name: "Pioneer",
          env: ["PIONEER_API_KEY"],
          options: {
            baseURL: "<https://api.pioneer.ai/v1>"
          },
          models: (
            {"auto": {"id": "pioneer/auto", "name": "Pioneer Auto"}}
            + (
              [catalog_models[]
                | select(.deprecated != true)
                | select(model_id != null)
                # Hide Claude Code discovery aliases so OpenCode does not show every model twice.
                | select(model_id | startswith("anthropic/pioneer/") | not)
                # Add the router once as the pioneer/auto model below, even if /v1/models includes it.
                | select(model_id != "pioneer/auto" and model_id != "auto")
                | {key: model_id, value: opencode_model}]
              | from_entries
            )
          )
        }
      })
    }' > "$CONFIG_TMP"

jq '. + {pioneer: {type: "api", key: env.PIONEER_API_KEY}}' "$AUTH_FILE" > "$AUTH_TMP"
chmod 600 "$AUTH_TMP"
mv "$CONFIG_TMP" "$CONFIG_FILE"
mv "$AUTH_TMP" "$AUTH_FILE"

Start and switch models

Start OpenCode:

Use /models to switch between the Pioneer models you configured. One note: the /models list may show older models that Pioneer does not support. If you pick one of those, the request will not complete. Stick to the models in your Pioneer config, and you can confirm every completed request in your Pioneer inference logs.

You can grab a Pioneer API key at pioneer.ai. The full, always-current integration steps live in the Pioneer OpenCode docs.

Why use Pioneer with OpenCode

OpenCode's biggest strength is that it is model-agnostic. Pioneer turns that flexibility into two concrete advantages.

Behind a single base URL, Pioneer gives you Claude, GPT, and Gemini models side by side. You route each task to the right model without managing separate provider accounts or juggling API keys: a fast, inexpensive model like Claude Haiku 4.5 or GPT-4o mini for quick questions, a reasoning model for architecture decisions, and a coding-specialized model for implementation.

Coming soon: We are working with the OpenCode team to list Pioneer as a native inference provider. Once that lands, the setup will be shorter than the config block above. Until then, the OpenAI-compatible method here is the supported path, and we will update this guide when native support ships.

Set up other providers (non-Pioneer)

Pioneer is the fastest path, but OpenCode works with any provider you configure. The simplest way to add one is the /connect command in the terminal UI, which walks you through authenticating a provider. API keys and provider settings live in an opencode.json config file or in environment variables.

That config file supports both a global config and a project-local config, and merges them automatically, so you can set org-wide defaults and override them per repository. It defines your provider blocks, the default model, and the models each provider exposes.

For any provider that speaks the OpenAI API format, OpenCode uses the @ai-sdk/openai-compatible npm package, the same one the Pioneer block uses. You give it a base URL and an API key, list the models, and OpenCode treats them like any other option. Switch between configured models at any time with:

This is why a single endpoint in front of many models is worth setting up. Instead of wiring up separate credentials and provider blocks for Anthropic, OpenAI, and Google, and instead of losing visibility into what each request costs, you route everything through one OpenAI-compatible endpoint that fans out to many models. That is what Pioneer gives you.

Initialize your project and start coding

With a provider connected, move into the project you want to work on and start OpenCode:

cd

cd

cd

Then initialize it:

This analyzes your project and creates an AGENTS.md file in the root. Commit that file to Git. It gives OpenCode durable context about your structure and coding patterns, so you do not have to re-explain your project on every run.

Ask questions and build features

You can ask questions about the codebase, using @ to fuzzy-search for files:

For a larger change, plan first. Press Tab to switch to Plan mode and describe what you want, in the level of detail you would give a junior engineer:

Once the plan looks right, press Tab again to return to Build mode and tell it to proceed. If a change is not what you wanted, undo it:

You can run /undo multiple times, and /redo to reapply.

Customize

From here you can pick a theme, remap keybinds, configure formatters, write custom commands, and add MCP servers. All of it is optional, and none of it is required to be productive on day one.

OpenCode vs other AI coding agents

The 2026 field of coding agents splits into open source terminal tools, IDE-first products, and vendor CLIs. Here is how OpenCode sits next to the main alternatives.

Where OpenCode wins. It is open source and MIT licensed, it works across terminal, desktop, and IDE, and it is not tied to any one model vendor. You pay only for tokens, and you can extend it with MCP servers, custom agents, and plugins.

Where the others win. Claude Code is the most complete agentic runtime on the benchmarks today, and its persistent CLAUDE.md context file is excellent. Cursor is IDE-first and has moved fast on cloud and parallel agents. Codex CLI posts the top Terminal-Bench scores with GPT-5.5. Aider pioneered the git-native workflow, though its 2026 model guidance is less actively maintained than the others. If you live in an IDE rather than a terminal, Cline and Kilo Code are the strongest open source options, both bring-your-own-key and model-agnostic, with Kilo Code reaching across VS Code, JetBrains, and the CLI. Pi is the pick if you want a minimal harness to reshape into your own tooling. Devin is the outlier: a proprietary, cloud-hosted autonomous engineer that runs long tasks on its own rather than a local agent you drive. Hermes and OpenClaw sit at the autonomous-agent end of the spectrum, both open source and model-agnostic: Hermes brings a persistent-memory learning loop from Nous Research, and OpenClaw is a viral self-hosted personal agent that runs skills across your machine rather than a focused coding harness.

Choose OpenCode when you want control, model choice, and no lock-in.

Common workflows and tips

• Plan before you build. For anything beyond a small edit, use Plan mode first. Reviewing intent before the agent touches files catches wrong assumptions early and saves cleanup.

• Invest in AGENTS.md. Document your architecture, conventions, and the patterns you do not want the agent to use. A good AGENTS.md is the difference between an agent that fits your codebase and one that fights it.

• Route models by task. Use a fast, inexpensive model for quick questions, a reasoning model for design decisions, and a coding-specialized model for implementation. With Pioneer this is one easy step by typing /models and choosing pioneer/auto as your model.

• Run parallel sessions. Keep a research session and an implementation session open at once, each with its own context window.

• Share when you need a second set of eyes. /share creates a link to the current conversation for a teammate.

• Add MCP servers for external context. Connect the tools and services your agent needs so it can pull in context beyond the local repo.

Troubleshooting and FAQ

• Is OpenCode free?

  The tool is free and MIT licensed. You pay only for the model tokens you consume through whatever provider you configure.

• Does OpenCode work on Windows?

  Yes. We recommend running it inside WSL for the best performance and full feature compatibility.

• What models does OpenCode support?

  Effectively any model, through 75+ built-in providers or any OpenAI-compatible endpoint such as Pioneer.

• OpenCode vs Claude Code, which is better?

  Claude Code leads the benchmarks today and is tightly integrated with Anthropic's models. OpenCode is open source and model-agnostic. If you want vendor-independent control and model choice, OpenCode is the better fit.

• How do I run many models cheaply from one place?

  Point OpenCode at Pioneer. One endpoint gives you access to a range of Claude, GPT, and Gemini models, with inference logs and continual optimization included.

• A model shows in /models but requests fail.

  OpenCode may list models your provider does not serve. If you are on Pioneer, use the models in your Pioneer config, and verify completed requests in your Pioneer inference logs.

Conclusion

OpenCode is the open source, terminal-first coding agent for developers who want a real agent harness without vendor lock-in. Install it in a minute, initialize your project with /init, plan and build with a Tab keypress, and bring whatever model you want. When you route that model choice through Pioneer, you get many models behind one endpoint, full visibility into your inference, and a feedback loop that makes your model cheaper and better the more you use it.

Get a Pioneer API key at pioneer.ai, follow the OpenCode integration docs, and run your first OpenCode session through Pioneer today.