2364 words
12 minutes
Getting Started with OpenCode
2026-04-07

Getting Started with OpenCode#

1. Introduction#

OpenCode is an open-source, terminal-based AI coding assistant in the same family as Claude Code and Gemini CLI. It lets you talk to LLMs right in your terminal to write, debug, and refactor code.

Unlike traditional IDE plugins, OpenCode lives in the terminal, which makes it a natural fit for servers and remote development. It also plugs into a wide range of model providers, so you’re free to pick whatever AI model suits you best.

This guide takes you from a clean machine to a working OpenCode setup: installing and configuring it, getting familiar with everyday usage and common commands, and then introducing advanced plugins like oh-my-openagent to unlock the full potential of AI-assisted coding.


2. Setting Up a Network Proxy#

Node.js, OpenCode, and friends can be slow or flaky to download depending on your network. It’s worth setting up a proxy first.

  1. Open the registration link and create an account: https://love.p6m6.com/#/register?code=sAkUiL1y

  2. Pick the “Starter Poké Ball” plan and enter the promo code 耿鬼 (it’s free — 0 CNY) Enter the promo code and purchase the plan

  3. Download the proxy client as the page instructs, then click “Import Subscription” Import the subscription

  4. Once downloaded, open the proxy client, switch the mode to “Rule-based Proxy”, and turn the proxy on

  5. Open your browser and visit Google — if it loads, the proxy is working

  6. To use the proxy in a terminal: open the proxy client’s settings, find the “Copy Environment Variables” option, switch to the PowerShell flavor, and paste the copied text into your PowerShell terminal. Any downloads you run in that terminal will go through the proxy Copy environment variables to the terminal

    macOS: choose the bash or zsh terminal type and paste into Terminal

    Windows (under WSL): choose the bash terminal type and paste into your WSL terminal

Tip: every new terminal window needs the environment variables pasted again before the proxy takes effect.


3. Installation#

3.1 macOS#

Open Terminal and install with whichever method you prefer:

Option 1: Homebrew (officially recommended)

Terminal window
brew install anomalyco/tap/opencode

Option 2: One-line install script

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

Option 3: npm

Terminal window
npm install -g opencode-ai

3.2 Windows#

On Windows, the best experience is running OpenCode through WSL — that’s the officially recommended route.

Right-click the Start menu → Windows PowerShell (Admin) or Terminal (Admin)

Step 1: Install WSL

Terminal window
wsl --install

Restart your computer after it finishes. Once you’re back, open PowerShell (Admin) again and run the following to set up the environment:

Terminal window
# Start WSL
wsl
# Set a username and password when prompted
# Update package sources
sudo apt update && sudo apt upgrade -y
# Install dependencies
sudo apt install -y curl git

Step 2: Install OpenCode

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

3.3 Verify the Installation#

Once installed, confirm it works:

Terminal window
opencode -v
# Example output: 1.2.24

4. Configuration#

Create and edit the config file:

macOS:

Terminal window
mkdir -p ~/.config/opencode && nano ~/.config/opencode/opencode.jsonc

Windows (under WSL):

Terminal window
mkdir -p ~/.config/opencode && nano ~/.config/opencode/opencode.jsonc

Alternative editors (recommended):

  • VS Code (best option — IntelliSense + schema autocompletion)

    Terminal window
    code ~/.config/opencode/opencode.jsonc

    Prerequisite: VS Code installed inside WSL, or VS Code on Windows with the Remote-WSL extension

  • Vim

    Terminal window
    vim ~/.config/opencode/opencode.jsonc
  • Edit directly from Windows Explorer (no need to enter WSL)

    Type \\wsl$\Ubuntu\home\<your-wsl-username>\.config\opencode in the address bar (replace Ubuntu with your distro name, e.g. Ubuntu-22.04), then open opencode.jsonc with Notepad or Notepad++

Fill in the following:

{
"$schema": "https://opencode.ai/config.json",
"disabled_providers": ["google-vertex", "google-vertex-anthropic"],
"provider": {
"cpa": {
"name": "CPA",
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "your service URL",
"apiKey": "your API key"
},
"models": {
"gpt-latest": {
"name": "gpt-latest(high)",
"cost": {
"input": 2.5,
"output": 15,
"cache_read": 0.25,
"cache_write": 0,
"context_over_200k": {
"input": 5,
"output": 22.5,
"cache_read": 0.5,
"cache_write": 0,
},
},
},
"gpt-codex-latest": {
"name": "gpt-codex-latest(xhigh)",
"cost": {
"input": 1.75,
"output": 14,
"cache_read": 0.175,
"cache_write": 0,
},
},
},
}
},
"autoupdate": true,
}

Notes:

  1. gpt-latest points to the newest GPT model — currently GPT-5.4
  2. gpt-codex-latest points to the newest GPT Codex model — currently GPT-5.3-codex
  3. The token in parentheses after each model name is its reasoning effort level, one of low, medium, high, or xhigh. Higher levels are more capable, but burn more tokens and respond more slowly

5. Usage#

First, cd into your project:

Terminal window
# macOS
cd ~/project
# Windows (under WSL)
cd /mnt/c/Users/<your-username>/project

How Windows paths map to WSL paths:

Windows PathWSL Path
C:\/mnt/c/
D:\/mnt/d/
C:\Users\<user>\Documents/mnt/c/Users/<user>/Documents

5.1 Terminal Mode (TUI)#

Terminal window
opencode

5.2 Web Mode#

Terminal window
opencode web

6. Common Commands#

6.1 CLI Commands (typed directly in the terminal)#

CommandDescription
opencodeLaunch the TUI (what you’ll use most)
opencode -vPrint the version
opencode -hShow help
opencode upgradeUpgrade to the latest version
opencode run "your prompt"Non-interactive mode for one-off tasks
opencode modelsList all available models
opencode session listShow past sessions
opencode -s <session_id>Resume a specific session
opencode serveStart a headless server (for Desktop / Web)
opencode webLaunch the web UI
opencode statsShow token usage statistics

6.2 Built-in TUI Commands (type / inside the UI)#

CommandDescription
/connectConnect to or switch model providers
/modelsView and switch models
/initInitialize the project (creates AGENTS.md)
/newStart a new session
/compactManually compact the context
/undoUndo the last action
/redoRedo
/shareGenerate a share link
/helpShow all commands

7. Advanced Configuration#

7.1 The oh-my-openagent Plugin#

7.1.1 Overview#

oh-my-openagent (OMO for short, formerly oh-my-opencode) is the most popular multi-agent plugin in the OpenCode ecosystem. It upgrades OpenCode from a single AI assistant into a highly autonomous AI team: a Sisyphus master coordinator dispatches specialist sub-agents working in parallel, automating complex software engineering tasks to the point where you can hand off a task, go grab a coffee, and come back to it done.

7.1.2 Core Features#

Execution Modes#

Ultra Work (ulw)

The flagship execution mode. Type ulw + a task description and every agent activates at once — planning, executing in parallel, and self-correcting, running continuously until the task is done with no manual intervention.

Ralph Loop (/ulw-loop)

A self-referential execution loop that pairs with Ultra Work. The agent keeps iterating until the goal is fully met — ideal for complex tasks that need multiple rounds of edits and verification.

Deep Initialization (/init-deep)

Automatically generates a hierarchy of AGENTS.md files across your project tree, giving every agent layered, scoped context — saving tokens while improving each agent’s understanding of the project.

Planning Mode (/start-work)

An interview-style planning flow driven by the Prometheus agent. Before writing any code, it asks you questions, clarifies requirements, and nails down scope like a real engineer would, then produces a detailed execution plan.

Quality Guardrails#

IntentGate

Analyzes what the user actually means before classifying or executing an action, guarding against literal misreadings of a prompt.

Hashline (hash-anchored edits)

Every line the agent reads gets tagged with a content hash (e.g. 11#VK|); edits reference these tags, and any change with a mismatched hash is rejected outright — preventing file corruption at the source. Per the official report, edit success rate went from 6.7% to 68.3%.

Todo Enforcer

Automatically pulls agents back on track when they drift, ensuring the current task never gets dropped or forgotten.

Comment Checker

Blocks low-quality AI-generated comments, keeping code comments professional and readable.

Toolchain Integration#

LSP and AST-Grep

  • LSP tools: lsp_rename, lsp_goto_definition, lsp_find_references, lsp_diagnostics
  • AST-Grep: pattern-aware search and rewrite across 25 languages

Built-in MCP Services

  • Exa — web search
  • Context7 — official documentation lookup
  • Grep.app — GitHub code search

Skill-Embedded MCPs

Each skill can carry its own MCP servers, spun up on demand and torn down after use so they never eat into your context window. Built-in skills include playwright (browser automation), git-master (atomic commits / rebases), and frontend-ui-ux (design-first UI development).

Tmux Integration

Full interactive terminal support — run REPLs, debuggers, and TUI apps inside agent sessions.

Smart Model Routing

Automatically picks the best model for the task type (e.g. Claude for planning, GPT Codex for coding), routing by category rather than by specific model to stay efficient while saving tokens.

Full Claude Code Compatibility

Existing Hooks, Commands, Skills, MCPs, and plugins all work as-is, no changes needed.

7.1.3 Installation#

Inside the OpenCode terminal, just send the following and let the LLM handle the installation:

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

If installation succeeded, restart OpenCode and the default mode should now read Sisyphus (Ultraworker).

Successful installation

7.1.4 Configuring Models#

oh-my-openagent ships with official GPT, Claude, and Gemini models configured by default. Since we’re using the CPA provider, the config file needs a manual edit.

Open the oh-my-opencode config:

macOS:

Terminal window
code ~/.config/opencode/oh-my-opencode.json

Windows (under WSL):

Terminal window
code ~/.config/opencode/oh-my-opencode.json

You can substitute nano or vim for code — see section 4 above for editing options.

Replace the contents with:

{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/assets/oh-my-opencode.schema.json",
"agents": {
"sisyphus": {
"model": "cpa/gpt-latest",
"variant": "high"
},
"hephaestus": {
"model": "cpa/gpt-codex-latest",
"variant": "xhigh"
},
"oracle": {
"model": "cpa/gpt-latest",
"variant": "xhigh"
},
"librarian": {
"model": "cpa/gpt-codex-latest",
"variant": "high"
},
"explore": {
"model": "cpa/gpt-codex-latest",
"variant": "high"
},
"multimodal-looker": {
"model": "cpa/gpt-latest",
"variant": "high"
},
"prometheus": {
"model": "cpa/gpt-latest",
"variant": "xhigh"
},
"metis": {
"model": "cpa/gpt-latest",
"variant": "xhigh"
},
"momus": {
"model": "cpa/gpt-latest",
"variant": "xhigh"
},
"atlas": {
"model": "cpa/gpt-latest",
"variant": "high"
}
},
"categories": {
"visual-engineering": {
"model": "cpa/gpt-latest",
"variant": "high"
},
"ultrabrain": {
"model": "cpa/gpt-latest",
"variant": "xhigh"
},
"deep": {
"model": "cpa/gpt-codex-latest",
"variant": "xhigh"
},
"artistry": {
"model": "cpa/gpt-latest",
"variant": "high"
},
"quick": {
"model": "cpa/gpt-codex-latest",
"variant": "high"
},
"unspecified-low": {
"model": "cpa/gpt-codex-latest",
"variant": "high"
},
"unspecified-high": {
"model": "cpa/gpt-latest",
"variant": "high"
},
"writing": {
"model": "cpa/gpt-latest",
"variant": "high"
}
}
}

Note: this config assigns the two available models based on each agent’s and category’s role. Roles needing deep reasoning (planning, architecture, review) get gpt-latest + xhigh; deep-coding roles get gpt-codex-latest + xhigh; lightweight search and quick tasks get gpt-codex-latest + high (cheaper); general coordination and execution roles get gpt-latest + high.

7.1.5 Agents and Categories Reference#

Agents (Specialist Roles)#
AgentRoleRecommended ModelNotes
sisyphusMaster coordinatorClaude Opus / GLM-5Task decomposition, sub-agent dispatch, parallel scheduling, driving tasks to completion — the entry point for all complex work
hephaestusAutonomous deep-coding craftsmanGPT-5.3-codexExplores codebases, studies patterns, implements features end-to-end; built for deep coding
prometheusStrategic plannerClaude Opus / GLM-5Interview-style planning — questions the user, defines scope, builds a detailed plan before any code gets written
oracleArchitecture & debugging expertHigh-reasoning modelsArchitecture decisions, gnarly bug diagnosis, technical validation
librarianKnowledge & documentation curatorGeneral modelsCode and doc search, explaining existing code, writing documentation
exploreFast codebase scoutLightweight, fast modelsRapid scans and greps to locate change points and gather contextual evidence
multimodal-lookerMultimodal / visual analystMultimodal modelsHandles images, UI mockups, and screenshots, turning them into code or suggestions
metisPre-planning analystHigh-reasoning modelsWorks with Prometheus to surface risks, edge cases, dependencies, and trade-offs
momusHarsh reviewer / quality criticHigh-reasoning modelsReviews code and plans, hunting bugs, security issues, and performance problems
atlasExecution maestro / deployerGeneral modelsFinal integration, deployment, environment setup, production-readiness checks

Note: the “Recommended Model” column reflects the official ideal configuration. Since we’re on the CPA provider only, the actual config above uses cpa/gpt-latest throughout.

Categories (Task Routing)#

When the Sisyphus coordinator assigns work, it automatically matches tasks to these categories, each with its own model and effort level:

CategoryDomainEffort LevelTypical Scenarios
visual-engineeringFrontend, UI/UX, visual designHigh (visual / multimodal)Building interfaces, CSS, components, design systems
ultrabrainBrutally hard logic, heavy architecture, complex algorithmsExtreme (long thinking)System design, distributed systems, performance-critical logic
deepGoal-oriented deep problem-solvingMedium-high (autonomous execution)End-to-end feature work, deep refactors, cross-module changes
artistryCreative / unconventional solutionsHigh (divergent thinking)Inventing new patterns, clever optimizations, out-of-the-box ideas
quickTrivial, quick changesMinimal (least thinking)Typos, one-line changes, quick renames
unspecified-lowUnclassified simple generic tasksLowMisc small chores, boilerplate
unspecified-highUnclassified important complex tasksHighImportant work that didn’t match a category
writingDocs, comments, READMEsNatural-language-firstWriting docs, changelogs, blog posts, test descriptions

Beyond these built-ins, oh-my-openagent supports custom categories you can extend to fit your team’s needs.

7.2 MCP#

MCP (Model Context Protocol) is a standardized protocol that lets AI models reach external tools and data sources. With MCP configured, OpenCode can connect to local scripts, remote knowledge bases, or specialized services for extra capabilities.

Add an mcp field to your config file (macOS: ~/.config/opencode/opencode.jsonc, Windows: %USERPROFILE%\.config\opencode\opencode.jsonc). OpenCode supports two kinds of MCP services:

  • Remote: connects to a remote HTTP/HTTPS endpoint, nothing to install locally
  • Local: runs a local command or script as the MCP service

1. Context7 — Official Documentation Lookup

Queries up-to-date docs and code examples for any programming library in real time, keeping the AI off stale APIs.

{
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
},
},
}

2. Grep.app — GitHub Code Search

Searches public code on GitHub to quickly find real-world usage and reference implementations.

{
"mcp": {
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app",
},
},
}

3. Exa — Web Search

Gives the AI live web search for current information and technical articles. Requires an Exa API key.

{
"mcp": {
"exa": {
"type": "local",
"command": ["npx", "-y", "exa-mcp-server"],
"environment": {
"EXA_API_KEY": "your Exa API key"
},
},
},
}

Combined Configuration Example#

You can enable several services at once by merging them into the mcp field:

{
"$schema": "https://opencode.ai/config.json",
// ... other settings (provider, etc.)
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
},
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app",
},
},
}

Management Commands#

CommandDescription
opencode mcp addInteractively add an MCP service
opencode mcp listList all configured MCP services
opencode mcp auth <name>Authenticate with a specific service
opencode mcp debug <name>Check connection status and health

Tip: every MCP service adds context overhead. Enable only what you currently need — too many tools can push you over the token limit.

Skills are OpenCode’s plugin system for capabilities. Each skill bundles domain-specific instructions, embedded MCP services, and preset permissions, and activates automatically in relevant situations once installed — no manual invocation needed.

ui-ux-pro-max — AI-Powered UI/UX Design Intelligence#

Scope: frontend projects only. This skill is built for frontend UI/UX work and doesn’t apply to backends, CLI tools, data processing, or anything without a UI. Skip it if your project has no interface work.

ui-ux-pro-max is a design-intelligence skill for frontend developers. Describe a UI need to the AI and it generates a complete design system first (colors, typography, layout, style, anti-pattern checks), then produces high-quality code built on that system.

Core Capabilities

  • Design system generator: describe the project in natural language and get a full design system — layout patterns, visual style, color schemes, font pairings, effect suggestions, and an anti-pattern checklist
  • 161 industry reasoning rules: covering SaaS, fintech, e-commerce, healthcare, restaurants, gaming, Web3, and more; each rule includes recommended layouts, style priorities, color tones, and typography advice
  • 67 UI styles: Glassmorphism, Neumorphism, Brutalism, Bento Grid, Liquid Glass, Cyberpunk UI, Aurora UI, and other mainstream and cutting-edge looks
  • 57 curated font pairings: with Google Fonts links, ready to use
  • 161 color schemes: matched to product type for industry-appropriate palettes
  • 25 chart types: for dashboards and data analysis

Supported Tech Stacks

CategoryFrameworks
Web (default)HTML + Tailwind CSS
React ecosystemReact, Next.js, shadcn/ui
Vue ecosystemVue, Nuxt.js, Nuxt UI
Other webSvelte, Astro
iOSSwiftUI
AndroidJetpack Compose
Cross-platformReact Native, Flutter

Installation

Prerequisite: Python 3.x

Terminal window
# Install the CLI
npm install -g uipro-cli
# Initialize inside your project (select opencode as the AI tool)
cd /path/to/your/project
uipro init --ai opencode

Usage

Nothing to do after installing. When you make a UI/UX-flavored request in OpenCode (anything like build, design, create, implement, review, fix, improve), the skill kicks in automatically and runs this flow:

  1. Analyzes your request and matches it to a product type and industry rules
  2. Generates the full design system (colors, fonts, layout, style)
  3. Produces code based on that system, keeping colors, spacing, and best practices consistent
  4. Checks for common anti-patterns before delivery

Tip: name your stack in the prompt (e.g. “with Next.js + shadcn/ui”) for more precise output. Without one, it defaults to HTML + Tailwind CSS.

Getting Started with OpenCode
https://www.mihouo.com/en/posts/ai/opencode-入门指南/
Author
Jia
Published at
2026-04-07
License
CC BY-NC-SA 4.0