The Complete Guide to OpenCode: The Open-Source AI Coding Assistant

AI-powered coding tools are everywhere these days. While products like Claude Code and Cursor are undeniably powerful, they come with trade-offs—steep pricing, closed-source codebases, or both. OpenCode changes the game. It's a fully open-source, free-to-use AI coding agent that supports 75+ model providers. Whether you're a full-stack developer, an indie hacker, or an open-source contributor, OpenCode can become your go-to coding companion right in the terminal. This guide walks you through everything—from installation and basic usage to core concepts, advanced techniques, and multi-agent collaboration.

1. What Is OpenCode?

OpenCode is an open-source AI agent coding tool that works through a terminal UI (TUI), desktop application, or IDE extension. Its core philosophy: open-source, privacy-first, and highly customizable AI programming assistance.

Here's how it stacks up against similar tools:

Cursor Agent: Closed-source commercial product, tied to specific models, expensive monthly subscription
Claude Code: Closed-source, only supports Anthropic models, pay-per-token billing
OpenCode: Fully open-source, supports 75+ model providers, includes built-in free models, can connect to local models, native terminal experience

OpenCode supports 75+ model providers, ships with free models like GLM-4.7 and MiniMax M2.1, integrates with commercial APIs from OpenAI, Anthropic, and Google, and can even be configured to use local models (like Llama 3). Whether you're writing quick scripts or building complex architectures, it adapts to your needs.

2. Installing OpenCode

2.1 System Requirements & Platform Notes

OpenCode runs on macOS, Linux, and Windows (via WSL). For the best experience, use a modern terminal emulator:

WezTerm: Cross-platform, feature-rich
Alacritty: Cross-platform, GPU-accelerated
Ghostty: Linux & macOS, excellent performance
Kitty: Linux & macOS, highly capable

Important: OpenCode doesn't natively support Windows. Windows users must use WSL (Windows Subsystem for Linux), a virtual machine, or Docker.

2.2 One-Click Installation (Recommended)

The simplest method for macOS and Linux:

bash

1	`# One-click install script`
2	`curl -fsSL https://opencode.ai/install \| bash`

Windows users can use PowerShell:

powershell

1	`Invoke-WebRequest -Uri https://opencode.ai/install -UseBasicParsing \| Invoke-Expression`

Verify the installation:

bash

1	`opencode --version`
2
3	`# You should see a version number like 1.1.19`

2.3 Package Manager Installation

Choose the right package manager for your OS:

bash

# macOS / Linux - Homebrew
brew install opencode
 
# macOS / Linux - npm (requires Node.js)
npm install -g opencode-ai
 
# Windows - Chocolatey
choco install opencode
 
# Windows - Scoop
scoop bucket add extras
scoop install extras/opencode
 
# Arch Linux
paru -S opencode-bin

2.4 Desktop Application

If you prefer a graphical interface, OpenCode also offers a desktop app. Download the installer for your platform from the GitHub Releases page or opencode.ai/download:

macOS (Apple Silicon): opencode-desktop-darwin-aarch64.dmg
macOS (Intel): opencode-desktop-darwin-x64.dmg
Windows: opencode-desktop-windows-x64.exe
Linux: .deb, .rpm, or AppImage formats

3. First Launch & Model Configuration

3.1 Launching OpenCode

Navigate to your project directory and start OpenCode:

bash

1	`cd /path/to/your/project`
2	`opencode`

The first launch walks you through basic setup, including model selection and sign-in options.

3.2 Choosing a Free Model (Zero-Cost Setup)

OpenCode includes several built-in free models that work without any API key. After launching, type /models to see available models—those marked with Free are ready to use at no cost:

GLM-4.7: A high-quality model from Zhipu AI
MiniMax M2.1: A free model from MiniMax

Simply select one of these free models and you're good to go—no costs involved.

3.3 Connecting Commercial Models (Optional)

If you have API keys for commercial models, you can configure them in a few ways:

Option 1: Use the /connect command

Inside the OpenCode TUI, type:

code

1	`/connect`

Then select a model provider from the list (e.g., Anthropic, OpenAI, Google) and paste your API key when prompted.

Option 2: Use the CLI login

bash

1	`opencode auth login`

Option 3: Use OpenCode Zen recommended models

OpenCode Zen is a curated set of officially recommended, thoroughly tested models that saves you the hassle of managing multiple external accounts. Just select OpenCode Zen from the /connect menu.

3.4 Manual Configuration File (Advanced)

You can edit the configuration file directly for fine-grained control over model settings. Config file locations:

Global config: ~/.config/opencode/opencode.json
Project config: opencode.json in the project root

Here's a complete example showing how to add a custom model provider:

json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Canopy Wave",
      "options": {
        "baseURL": "https://inference.canopywave.io/v1",
        "headers": {
          "Authorization": "Bearer your_api_key_here"
        }
      },
      "models": {
        "zai/glm-4.7": {
          "name": "glm47"
        }
      }
    }
  }
}

Just replace `your_api_key_here` with your actual API key.

4. Core Concepts & Working Modes

4.1 Two Agent Modes

OpenCode features two core working modes, which you can toggle instantly with the Tab key:

Plan Mode (Read-Only Planning)

In this mode, the AI can only analyze your project and plan tasks—it can't modify any files. Think of it as a technical advisor that helps you analyze problems and devise solutions without touching your code.

Ideal for:

Exploring a new codebase and understanding its structure
Breaking down complex requirements into manageable tasks
Evaluating multiple implementation approaches before committing

Build Mode (Full Permissions)

In Build mode, the AI has full authority to read and write files, run commands, and modify code.

Ideal for:

Executing code changes after confirming a plan
Running tests and building the project
Making specific code modifications

Recommended Workflow:

code

1	`Plan mode to discuss requirements → AI proposes a solution → Iterate and confirm → Tab to switch to Build → Execute → Verify`

This design strikes a balance between safety and efficiency.

4.2 Project Initialization & AGENTS.md

When you first enter a project, run the initialization command:

code

/init

This does two things:

Creates the .opencode/ directory: Stores the project's vectorized index and custom instructions
Generates an AGENTS.md file: Automatically scans the project structure and generates a project context description

AGENTS.md is the core file OpenCode uses to understand your project. It gets injected as a global prompt into every conversation. You can manually edit it to include:

Tech stack and architecture descriptions
Coding standards and naming conventions
Common pitfalls and important notes
Key module responsibilities

4.3 Built-in Tool Set

OpenCode's AI agent interacts with your codebase through the following tools. Permissions for each can be configured in opencode.json using allow/deny/ask settings:

bash: Execute shell commands (e.g., git status, npm test)
write/edit/patch: Create, modify, and patch files
read: Read file contents (supports line ranges)
grep/glob/list: Search and list files (automatically respects .gitignore)
webfetch: Fetch web page content (for looking up documentation)
lsp (experimental): Code navigation, hover info, etc.
question: Ask you for confirmation
todo: Maintain a task checklist

In addition, OpenCode supports custom tools and MCP (Model Context Protocol) server extensions—for example, connecting to databases or invoking search engines.

5. Basic Usage in Practice

5.1 Building a Complete Project from Scratch

Here's a full walkthrough for creating a Node.js API from the ground up:

bash

# 1. Create the project directory
mkdir my-api && cd my-api
 
# 2. Initialize a Node.js project
npm init -y
 
# 3. Launch OpenCode
opencode

Inside the OpenCode TUI, run these steps:

code

# Step 1: Initialize project context
/init
 
# Step 2: Describe your requirements
Create an Express.js server with a /hello route that returns JSON { message: 'Hello World' }, and add a README

OpenCode will automatically analyze the requirements, install dependencies, create files, and write the code.

5.2 Asking Questions About Your Code

You can ask questions about your codebase using natural language. Use the @ symbol to reference specific files:

code

1	`What functionality does @index.html contain?`

code

1	`Analyze the validation logic in @src/utils/validation.js`

code

1	`Explain the authentication logic in src/main.ts`

5.3 Common Day-to-Day Operations

Here's a quick reference for everyday interactions:

code

# Add a new feature
Add a user registration API with email verification
 
# Fix a bug
Fix the null pointer exception in the login function
 
# Refactor code
Extract the duplicated logic in @src/utils/helpers.js into a shared utility function
 
# Undo and redo
/undo          # Undo the last operation (requires a Git repo)
/redo          # Redo an undone operation
 
# Session management
/compact       # Compress the session to prevent hitting context limits
/share         # Generate a shareable link
/new           # Start a new session

5.4 Image Analysis

OpenCode supports image uploads—UI mockups, architecture diagrams, and more. You can paste a Figma design screenshot and have OpenCode generate frontend code based on it. This is incredibly useful for UI development workflows.

6. Slash Commands Quick Reference

Mastering these slash commands will significantly boost your productivity:

Core Configuration Commands

/connect — Add or configure an LLM provider (API Key)
/init — Create or update the project's AGENTS.md file (shortcut: Ctrl+X I)
/models — List available models and switch between them (shortcut: Ctrl+X M)

Session Management Commands

/new — Start a new session (alias: /clear, shortcut: Ctrl+X N)
/sessions — List and switch between sessions (alias: /resume, shortcut: Ctrl+X L)
/share — Share the current session via a generated link (shortcut: Ctrl+X S)
/compact — Compress and summarize the current session (shortcut: Ctrl+X C)

Editing & Undo Commands

/undo — Undo the last operation (requires a Git repo, shortcut: Ctrl+X U)
/redo — Redo an undone operation (requires a Git repo, shortcut: Ctrl+X R)

View & Utility Commands

/details — Toggle tool execution detail display
/thinking — Toggle thinking process visibility
/theme — List and switch themes
/help — Show help information
/editor — Compose a message using an external editor
/exit — Exit OpenCode (aliases: /quit, /q)

7. CLI Arguments

Beyond the interactive TUI, OpenCode also supports non-interactive mode—ideal for scripts and automation:

bash

# Non-interactive mode: run a prompt and output the response
opencode -p "Fix the bug in the login function"
 
# Specify a working directory
opencode -c /path/to/your/project
 
# Output as JSON (great for script parsing)
opencode -p "Explain the code" -f json
 
# Quiet mode (hide the loading animation)
opencode -p "Run the tests" -q
 
# Debug mode (verbose logging)
opencode -d

Arguments Quick Reference

--help / -h: Display help information
--debug / -d: Enable debug mode
--cwd / -c: Specify the working directory
--prompt / -p: Run a prompt in non-interactive mode
--output-format / -f: Output format (text or json)
--quiet / -q: Hide the loading animation

8. Advanced Usage & Best Practices

8.1 Custom Commands

You can create Markdown files in ~/.config/opencode/commands/ to define custom commands. For example, create a file called prime-context.md:

markdown

Start by analyzing the complete structure of the current project. List key files and modules, then summarize the project's core functionality and architectural patterns.
Focus on:
1. Entry points and routing structure
2. Data models and database design
3. Third-party dependencies and integrations
4. Test coverage

Once saved, you can quickly invoke this pre-loaded prompt as a custom command from within OpenCode.

8.2 Permission Control

In opencode.json, you can set permission levels for each tool:

allow: Execute automatically, no confirmation needed
deny: Block usage entirely
ask: Require manual confirmation before each execution

For sensitive operations like file deletions or database changes, it's a good practice to set the permission to ask.

8.3 Parallel Sessions

OpenCode supports running multiple agent sessions simultaneously for different tasks. Use /sessions to view all active sessions and quickly switch between them.

8.4 IDE Integration

OpenCode currently supports a VS Code extension (search for "OpenCode extension" in the marketplace) and can also be controlled remotely through its client/server architecture.

8.5 Productivity Tips

Leverage AGENTS.md: Manually edit this file to capture all the critical information about your project. The better the AI understands your codebase, the higher the quality of its output.

Use @ for file references: Use the @ symbol to precisely reference files in your conversations. It's far more efficient than vaguely describing file paths.

Compress sessions regularly: During long conversations, use /compact to compress the context and avoid exceeding the context window.

Plan first, then Build: Make it a habit to plan before executing. This prevents the AI from making incorrect changes due to misunderstandings.

9. Oh-My-OpenCode: Multi-Agent Collaboration

If OpenCode is a powerful AI coding assistant, Oh-My-OpenCode transforms it into a full AI development team. This extension (think Oh-My-Zsh for Zsh) introduces a multi-agent collaboration system where multiple specialized AI agents work in parallel.

9.1 Installing Oh-My-OpenCode

Prerequisite: You need the Bun runtime:

bash

1	`curl -fsSL https://bun.sh/install \| bash`

Restart your terminal, then run the installation:

bash

1	`# Adjust parameters based on your subscriptions`
2	`bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=yes --gemini=yes`

If you only have certain subscriptions, adjust accordingly:

bash

1	`# Claude subscription only`
2	`bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no`

If you run into issues with Bun, you can use npx instead:

bash

1	`npx oh-my-opencode install --no-tui --claude=yes`

Verify the installation:

bash

1	`cat ~/.config/opencode/opencode.json \| grep "oh-my-opencode"`

9.2 Agent Team Roles

Oh-My-OpenCode's core is a set of specialized agents, each with a clearly defined role:

Sisyphus (Lead Orchestrator): Responsible for task planning, assignment, and coordination. Recommended model: Claude 3.5 Sonnet
Oracle (Architecture Advisor): Handles architecture design and answers complex questions. Recommended model: GPT-4
Librarian (Documentation Expert): Manages documentation lookup and codebase research. Recommended model: Gemini 1.5 Flash
Frontend Engineer: Handles UI/UX development and interface design. Recommended model: Gemini 3 Pro
Explorer (Code Explorer): Performs quick code analysis and pattern discovery. Recommended model: Gemini Flash

9.3 Ultrawork Mode

This is Oh-My-OpenCode's most powerful feature. Include the keyword ultrawork or its shorthand ulw in your prompt:

code

1	`ultrawork: Help me implement a React component with dark mode toggle support`

Once activated, the Sisyphus lead agent takes over and automatically:

Analyzes task complexity and breaks it into subtasks
Assigns subtasks to the most suitable specialist agents
Runs multiple agents in parallel
Aggregates results and performs quality checks
Automatically tests and validates the output

9.4 Advantages of Multi-Model Collaboration

Oh-My-OpenCode's multi-model approach isn't just simple round-robin—it's genuine division of labor:

Complementary strengths: Different models excel in different areas—Claude is great at planning and text generation, GPT shines at reasoning, Gemini handles multimodal tasks well
Cost optimization: Lightweight models handle simple tasks while high-performance models tackle critical ones
Fault tolerance: If one model fails, it automatically falls back to a backup

9.5 Configuration File

Oh-My-OpenCode's configuration files are located at:

Global: ~/.config/opencode/oh-my-opencode.json
Project-level: .opencode/oh-my-opencode.json

Basic configuration example:

json

{
  "google_auth": false,
  "agents": {
    "frontend-ui-ux-engineer": {
      "model": "google/gemini-3-pro-high"
    },
    "oracle": {
      "model": "openai/gpt-5.2"
    }
  },
  "sisyphus_agent": {
    "disabled": false
  },
  "background_task": {
    "defaultConcurrency": 5
  }
}

10. FAQ & Troubleshooting

Notes for Windows Users

If you're on Windows, you must use WSL or a virtual machine. Running OpenCode directly on Windows will cause various compatibility issues.

Model Selection Tips

Model performance varies significantly. Here's our recommendation:

Start with the free models recommended by OpenCode Zen (e.g., GLM-4.7)
If results aren't satisfactory, try other models
For complex tasks, consider using Claude or GPT-4-level models

AI Isn't Infallible

OpenCode is powerful, but AI-generated code may still contain bugs or misinterpret your requirements. Always verify code quality yourself and fix issues as you find them.

Custom Slash Commands

You can create custom commands in `~/.config/opencode/commands/` or your project directory. These override built-in commands, allowing you to personalize the experience to your workflow.

Conclusion

As a fully open-source AI coding assistant, OpenCode stands out with three major advantages: free to use, broad model support, and a native terminal experience—making it a genuine alternative to commercial products. Let's recap the key takeaways:

Zero barrier to entry: Built-in free models, one-command install, up and running in minutes
Plan/Build dual modes: Plan first, then execute—safe and efficient
AGENTS.md project context: Helps the AI truly understand your project structure and conventions
Rich tool set: bash, file operations, search, LSP, and more—covering the entire development lifecycle
Oh-My-OpenCode extension: Multi-agent collaboration that upgrades a single assistant into an AI dev team
Flexible model configuration: From free models to commercial APIs, from cloud to local deployment—choose what fits your needs

Our recommended learning path: start with simple code questions, work your way up to building complete projects, and eventually explore Oh-My-OpenCode's multi-agent collaboration. Remember, AI is a tool, not a replacement—writing great code still relies on your own thinking and judgment. What OpenCode does is boost your efficiency, freeing you to focus more on architecture design and creative problem-solving.

1	`# macOS / Linux - Homebrew`
2	`brew install opencode`
3
4	`# macOS / Linux - npm (requires Node.js)`
5	`npm install -g opencode-ai`
6
7	`# Windows - Chocolatey`
8	`choco install opencode`
9
10	`# Windows - Scoop`
11	`scoop bucket add extras`
12	`scoop install extras/opencode`
13
14	`# Arch Linux`
15	`paru -S opencode-bin`

1	`{`
2	`"$schema": "https://opencode.ai/config.json",`
3	`"provider": {`
4	`"myprovider": {`
5	`"npm": "@ai-sdk/openai-compatible",`
6	`"name": "Canopy Wave",`
7	`"options": {`
8	`"baseURL": "https://inference.canopywave.io/v1",`
9	`"headers": {`
10	`"Authorization": "Bearer your_api_key_here"`
11	`}`
12	`},`
13	`"models": {`
14	`"zai/glm-4.7": {`
15	`"name": "glm47"`
16	`}`
17	`}`
18	`}`
19	`}`
20	`}`

1	`# 1. Create the project directory`
2	`mkdir my-api && cd my-api`
3
4	`# 2. Initialize a Node.js project`
5	`npm init -y`
6
7	`# 3. Launch OpenCode`
8	`opencode`

1	`# Step 1: Initialize project context`
2	`/init`
3
4	`# Step 2: Describe your requirements`
5	`Create an Express.js server with a /hello route that returns JSON { message: 'Hello World' }, and add a README`

1	`# Add a new feature`
2	`Add a user registration API with email verification`
3
4	`# Fix a bug`
5	`Fix the null pointer exception in the login function`
6
7	`# Refactor code`
8	`Extract the duplicated logic in @src/utils/helpers.js into a shared utility function`
9
10	`# Undo and redo`
11	`/undo # Undo the last operation (requires a Git repo)`
12	`/redo # Redo an undone operation`
13
14	`# Session management`
15	`/compact # Compress the session to prevent hitting context limits`
16	`/share # Generate a shareable link`
17	`/new # Start a new session`

1	`# Non-interactive mode: run a prompt and output the response`
2	`opencode -p "Fix the bug in the login function"`
3
4	`# Specify a working directory`
5	`opencode -c /path/to/your/project`
6
7	`# Output as JSON (great for script parsing)`
8	`opencode -p "Explain the code" -f json`
9
10	`# Quiet mode (hide the loading animation)`
11	`opencode -p "Run the tests" -q`
12
13	`# Debug mode (verbose logging)`
14	`opencode -d`

1	`Start by analyzing the complete structure of the current project. List key files and modules, then summarize the project's core functionality and architectural patterns.`
2	`Focus on:`
3	`1. Entry points and routing structure`
4	`2. Data models and database design`
5	`3. Third-party dependencies and integrations`
6	`4. Test coverage`

1	`{`
2	`"google_auth": false,`
3	`"agents": {`
4	`"frontend-ui-ux-engineer": {`
5	`"model": "google/gemini-3-pro-high"`
6	`},`
7	`"oracle": {`
8	`"model": "openai/gpt-5.2"`
9	`}`
10	`},`
11	`"sisyphus_agent": {`
12	`"disabled": false`
13	`},`
14	`"background_task": {`
15	`"defaultConcurrency": 5`
16	`}`
17	`}`

The Complete Guide to OpenCode: The Open-Source AI Coding Assistant

1. What Is OpenCode?

2. Installing OpenCode

2.1 System Requirements & Platform Notes

2.2 One-Click Installation (Recommended)

2.3 Package Manager Installation

2.4 Desktop Application

3. First Launch & Model Configuration

3.1 Launching OpenCode

3.2 Choosing a Free Model (Zero-Cost Setup)

3.3 Connecting Commercial Models (Optional)

3.4 Manual Configuration File (Advanced)

Just replace your_api_key_here with your actual API key.

4. Core Concepts & Working Modes

4.1 Two Agent Modes

4.2 Project Initialization & AGENTS.md

4.3 Built-in Tool Set

In addition, OpenCode supports custom tools and MCP (Model Context Protocol) server extensions—for example, connecting to databases or invoking search engines.

5. Basic Usage in Practice

5.1 Building a Complete Project from Scratch

5.2 Asking Questions About Your Code

5.3 Common Day-to-Day Operations

5.4 Image Analysis

OpenCode supports image uploads—UI mockups, architecture diagrams, and more. You can paste a Figma design screenshot and have OpenCode generate frontend code based on it. This is incredibly useful for UI development workflows.

6. Slash Commands Quick Reference

Core Configuration Commands

Session Management Commands

Editing & Undo Commands

View & Utility Commands

7. CLI Arguments

Arguments Quick Reference

8. Advanced Usage & Best Practices

8.1 Custom Commands

8.2 Permission Control

8.3 Parallel Sessions

8.4 IDE Integration

8.5 Productivity Tips

Plan first, then Build: Make it a habit to plan before executing. This prevents the AI from making incorrect changes due to misunderstandings.

9. Oh-My-OpenCode: Multi-Agent Collaboration

9.1 Installing Oh-My-OpenCode

9.2 Agent Team Roles

9.3 Ultrawork Mode

9.4 Advantages of Multi-Model Collaboration

9.5 Configuration File

10. FAQ & Troubleshooting

Notes for Windows Users

Model Selection Tips

AI Isn't Infallible

Custom Slash Commands

You can create custom commands in ~/.config/opencode/commands/ or your project directory. These override built-in commands, allowing you to personalize the experience to your workflow.

Conclusion

Just replace `your_api_key_here` with your actual API key.

You can create custom commands in `~/.config/opencode/commands/` or your project directory. These override built-in commands, allowing you to personalize the experience to your workflow.