OpenCode Complete Guide: Installation, Configuration & All Features (2026)

What Is OpenCode?

OpenCode is an open-source AI coding assistant with 160K+ GitHub Stars, serving over 7.5 million developers each month. It runs in the terminal (TUI), IDE, and desktop environments, supporting 75+ model providers including Claude, GPT, Gemini, and more.

Unlike a simple chatbot, OpenCode is designed to be deeply integrated into your development workflow. It can read and edit files, execute shell commands, review pull requests, manage sessions, and orchestrate multi-agent coding tasks — all from your terminal.

This guide covers everything from installation to advanced features, so you can go from zero to productive in a single reading session.

Prerequisites

OS: Linux (Ubuntu/WSL2 recommended), macOS, or Windows (PowerShell / WSL2)
Terminal: Bash, Zsh, or Fish
Architecture: x86_64 or ARM64
Network: Access to GitHub and opencode.ai
Disk Space: At least 500 MB (the opencode binary is ~150 MB)
Node.js (optional): Required only for the npm installation method

Installation Methods

OpenCode offers four installation methods. Choose the one that best fits your environment.

Method 1: One-Line Script Install (Recommended)

This is the simplest way and works on Linux, macOS, and WSL2:

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

The script automatically:

Detects your operating system and CPU architecture
Downloads the matching release from GitHub Releases
Installs the binary to ~/.local/bin/opencode
Adds ~/.local/bin to your PATH in your shell config file (.bashrc / .zshrc)

Install a Specific Version

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

Skip Automatic PATH Modification

curl -fsSL https://opencode.ai/install | bash -s -- --no-modify-path

Sample Installation Output

OpenCode Installer v1.0.0
ℹ Detected OS: linux
ℹ Detected Architecture: x86_64
ℹ Downloading OpenCode v1.16.2...
✓ Downloaded to /tmp/opencode-xxxxx
✓ Installed to /home/user/.local/bin/opencode
✓ Added ~/.local/bin to PATH in ~/.bashrc
✓ Installation complete! Run 'opencode' to start.

Method 2: npm Install

If you already have Node.js (18+) and npm (9+) installed:

npm install -g @opencode/cli

Verify the installation:

opencode --version
# Output: 1.16.2

Note: The npm package may lag behind the latest release. For the newest version, use the curl script (Method 1).

Method 3: Homebrew (macOS)

brew install opencode

Method 4: Manual Install

Download the binary for your platform from GitHub Releases:

Open the releases page
Find the latest version
Download the archive for your platform (e.g., opencode-linux-x86_64.tar.gz)
Extract and move to a directory in your PATH:

tar -xzf opencode-linux-x86_64.tar.gz
mv opencode ~/.local/bin/
chmod +x ~/.local/bin/opencode

Windows Installation

Windows users can use PowerShell or WSL2:

# PowerShell (direct install)
iwr https://opencode.ai/install.ps1 | iex

# Or via Scoop
scoop install opencode

Verifying Installation

Once installed, confirm everything works:

opencode --version
# Should output a version number, e.g.: 1.16.2

opencode --help
# Should display all available commands

If you get command not found, ensure the install directory is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Then reload your shell: source ~/.bashrc (or open a new terminal).

First-Time Setup

1. Configure an AI Provider

OpenCode includes several free models by default, but to get the best experience you’ll want to connect your own API keys:

opencode providers

This opens an interactive UI where you can add credentials for:

OpenAI — GPT-4, GPT-4o, o1, o3
Anthropic — Claude Sonnet 4, Claude Opus
Google — Gemini 2.0 Pro, Gemini 2.0 Flash
OpenRouter — unified access to 200+ models
Local models — Ollama, vLLM, LM Studio
70+ other providers

You can also set provider credentials via environment variables:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-..."

2. Launch OpenCode

Navigate to a project directory and start a session:

cd your-project
opencode

This launches the TUI (terminal user interface), where you can chat with AI, read and edit files, and execute commands — all within your terminal.

Core Commands Reference

Command	Description
`opencode`	Launch the TUI interactive interface (default)
`opencode run "prompt"`	Execute a one-shot task from the command line
`opencode serve`	Start the headless server mode
`opencode web`	Launch the web interface
`opencode pr <number>`	Fetch and check out a GitHub PR branch
`opencode session`	Manage conversation sessions
`opencode models [provider]`	List available models
`opencode providers`	Manage AI provider configurations
`opencode stats`	View token usage statistics
`opencode mcp`	Manage MCP (Model Context Protocol) servers
`opencode agent`	Manage custom agents
`opencode upgrade`	Upgrade OpenCode to the latest version
`opencode uninstall`	Remove OpenCode from your system

TUI Mode

The TUI (Terminal User Interface) is OpenCode’s primary interaction mode, designed for extended coding sessions with full keyboard navigation.

Starting the TUI

# Start in the current directory
cd /path/to/project
opencode

# Start with a specific project path
opencode /path/to/project

# Resume the last session
opencode --continue
# or
opencode -c

# Resume a specific session
opencode --session ses_abc123
# or
opencode -s ses_abc123

# Launch TUI and immediately send a prompt (non-interactive)
opencode -p "Analyze this project's architecture and suggest improvements"

Keyboard Shortcuts

Shortcut	Function
`Enter`	Submit message (press twice when needed)
`Tab`	Switch between agents (e.g., build / plan)
`Ctrl+P`	Open the command palette
`Ctrl+X L`	Switch active session
`Ctrl+X M`	Switch model
`Ctrl+X N`	Create a new session
`Ctrl+X E`	Open the editor
`Ctrl+C`	Exit OpenCode

TUI Tips

Use Tab to cycle through available agents for different tasks
The command palette (Ctrl+P) gives quick access to all actions without remembering shortcuts
You can run TUI in the background for long-running tasks: opencode --demo "Describe your capabilities and wait" &

CLI Mode

CLI mode is ideal for automation, scripting, and one-shot tasks. Everything you can do in TUI, you can do from the command line.

Basic Usage

# Simple task
opencode run "Add retry logic to the API client"

# Attach files for context
opencode run "Review this config for security issues" -f config.yaml -f .env.example

# Show the model's thinking process
opencode run "Debug why the CI test is failing" --thinking

# Specify a model explicitly
opencode run "Refactor the auth module" --model openrouter/anthropic/claude-sonnet-4

Complete CLI Options

opencode run [message..]

Options:
  --command                    The command to execute (defaults to the message)
  --continue, -c               Continue the last session
  --session                    Resume a specific session by ID
  --share                      Share the session
  --model, -m                  Specify a model (provider/model format)
  --agent                      Specify an agent to use
  --format                     Output format: default | json
  --file, -f                   Attach a file (repeatable)
  --title                      Session title
  --attach                     Connect to a running opencode server
  --port                       Local server port
  --variant                    Model variant: high | max | minimal
  --thinking                   Display the model's thought process
  --replay                     Restore interaction history (default: true)
  --dangerously-skip-permissions   Auto-approve permissions not explicitly denied (dangerous!)

AI Provider Configuration

OpenCode supports 75+ model providers. Here’s how to manage them.

List Available Providers

opencode providers list
opencode auth list

Log In to a Provider

# Interactive login
opencode providers login

# Or set environment variables (takes precedence)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-..."

Provider Configuration Example

Add this to your ~/.config/opencode/opencode.json:

{
  "provider": {
    "anthropic": {
      "api": "https://api.anthropic.com",
      "env": ["ANTHROPIC_API_KEY"]
    },
    "openrouter": {
      "npm": "@opencode/plugin-openrouter",
      "env": ["OPENROUTER_API_KEY"]
    }
  },
  "enabled_providers": ["anthropic", "openrouter"],
  "disabled_providers": ["openai"]
}

Checking Available Models

# List all models
opencode models

# List models for a specific provider
opencode models openrouter

MCP Integration

MCP (Model Context Protocol) allows OpenCode to connect to external tools and services. Think of MCP servers as plugins that extend what OpenCode can do — filesystem access, database queries, API calls, and more.

List MCP Servers

opencode mcp list
opencode mcp ls

Add an MCP Server

# Add a stdio-based server
opencode mcp add filesystem -- "npx -y @modelcontextprotocol/server-filesystem /path/to/data"

# Add an SSE-based server on a custom port
opencode mcp add --port 3001 -- "node my-mcp-server.js"

Authenticate an MCP Server

opencode mcp auth myserver
opencode mcp logout myserver
opencode mcp debug myserver

Agent System

OpenCode supports creating custom agents — specialized AI personas tuned for specific tasks. Agents can have their own model, permissions, and behavior.

List Agents

opencode agent list

Create an Agent

opencode agent create my-agent \
  --description "Specialized in React component development" \
  --mode subagent \
  --model openrouter/anthropic/claude-sonnet-4

Agent Configuration Example

In ~/.config/opencode/opencode.json:

{
  "agent": {
    "code-reviewer": {
      "name": "Code Reviewer",
      "description": "Security and correctness expert",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4",
      "color": "#E74C3C",
      "permissions": ["read", "edit"]
    },
    "bug-hunter": {
      "name": "Bug Hunter",
      "description": "Debugging and fix specialist",
      "mode": "subagent",
      "model": "openai/gpt-4",
      "variant": "high",
      "permissions": ["bash", "read", "edit"]
    }
  }
}

Use an Agent

opencode run "Review this code for vulnerabilities" --agent code-reviewer

Switch between agents in TUI mode using the Tab key.

Session Management

Every conversation in OpenCode is a session. You can list, delete, export, and import them.

List Sessions

opencode session list

Delete a Session

opencode session delete ses_abc123

Export a Session

# Export the current session
opencode export

# Export a specific session
opencode export ses_abc123

# Export and sanitize sensitive info
opencode export ses_abc123 --sanitize

Import a Session

# Import from a local file
opencode import session.json

# Import from a share URL
opencode import https://opencode.ai/share/xxx

GitHub Integration

OpenCode can integrate directly with GitHub for pull request reviews.

Install the GitHub Agent

opencode github install

Run the GitHub Agent

opencode github run

Review a Pull Request

# Fetch PR #42 and launch opencode with it
opencode pr 42

# Review a PR by cloning into a temp directory
REVIEW=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW
cd $REVIEW
opencode run "Review the diff against main. Report bugs, security risks, test gaps, and style issues."

Server Mode

OpenCode can run as a server, allowing remote connections and web-based access.

Start a Headless Server

# Basic start
opencode serve

# Specify a port
opencode serve --port 4096

# Enable mDNS discovery
opencode serve --mdns
# Accessible at http://opencode.local:4096

Start the Web Interface

opencode web
# or with a custom port
opencode web --port 3096

Connect to a Remote Server

opencode attach http://hostname:4096

Configuration Reference

OpenCode’s configuration file lives at ~/.config/opencode/opencode.json. The file uses a JSON schema for validation and IDE autocompletion.

Full Configuration Example

{
  "$schema": "https://opencode.ai/config.json",

  "shell": "/bin/bash",

  "logLevel": "INFO",

  "server": {
    "port": 0,
    "hostname": "127.0.0.1",
    "mdns": false,
    "mdnsDomain": "opencode.local",
    "cors": []
  },

  "skills": {
    "paths": ["~/.config/opencode/skills"]
  },

  "model": "anthropic/claude-sonnet-4",
  "small_model": "openai/gpt-3.5-turbo",
  "default_agent": "build",
  "username": "developer",

  "share": "manual",

  "agent": {
    "build": {
      "name": "Build Agent",
      "description": "Default coding assistant agent",
      "model": "anthropic/claude-sonnet-4",
      "mode": "primary"
    }
  },

  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    }
  },

  "formatter": true,

  "lsp": true,

  "instructions": [
    "~/.config/opencode/instructions.md"
  ],

  "permission": {
    "read": {
      "~/**": "allow",
      "/etc/**": "deny"
    },
    "edit": {
      "**/*.go": "allow",
      "**/*": "ask"
    },
    "bash": "ask"
  }
}

Permission Configuration

Permission	Description	Values
`read`	File read access	`ask`, `allow`, `deny`
`edit`	File edit/write access	`ask`, `allow`, `deny`
`bash`	Shell command execution	`ask`, `allow`, `deny`

Permission entries support glob patterns. For example:

"~/projects/**": "allow" — allow read access to everything under ~/projects
"/etc/**": "deny" — deny access to system configuration files
"**/*": "ask" — ask for permission on everything else

The bash permission is especially sensitive — only set it to "allow" if you fully trust the model and environment.

Advanced Tips

1. Debugging Tools

# View current configuration
opencode debug config

# View system debug info
opencode debug info

# Inspect LSP debugging
opencode debug lsp

# Check startup time
opencode debug startup

# Inspect an agent configuration
opencode debug agent build

2. Usage Statistics & Cost Management

# View all stats
opencode stats

# View stats for the last 7 days
opencode stats --days 7

# Show top 5 models by usage
opencode stats --models 5

# Filter by project
opencode stats --project myproject

3. Plugin Management

OpenCode supports plugins for extending functionality:

# Install a plugin
opencode plugin opencode-plugin-github

# Install globally
opencode plugin --global opencode-plugin-docs

# Force reinstall
opencode plugin opencode-plugin-github --force

4. Upgrade & Uninstall

# Upgrade to the latest version
opencode upgrade

# Upgrade to a specific version
opencode upgrade 1.15.0

# Uninstall OpenCode
opencode uninstall

5. Shell Completions

Generate shell auto-completions for faster command entry:

# Generate bash completions
opencode completion

# Generate and save zsh completions
opencode completion >> ~/.zsh/completion/_opencode

Make sure the completion directory is in your fpath and enabled in your .zshrc.

6. ACP (Agent Client Protocol)

Start an ACP server for agent-to-agent communication:

opencode acp

7. Parallel Task Execution

Run multiple tasks simultaneously:

# Two tasks in parallel
opencode run "Fix issue #101" -m &
opencode run "Add parser regression tests" -m
wait

The -m flag runs in minimal mode (no TUI), and & pushes it to the background.

8. Smoke Test

Quickly verify that OpenCode is functioning:

opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'
# Successful output includes: OPENCODE_SMOKE_OK

Common Pitfalls & Troubleshooting

Pitfall 1: TUI Requires PTY Mode

Symptom: The TUI appears stuck or doesn’t accept input.

Cause: Interactive mode requires a pseudo-terminal (PTY). When running in the background or through certain wrapper scripts, PTY allocation may be missing.

Fix: Use the --continue flag in combination with -p for background tasks:

# Correct — works in background
opencode --continue -p "Wait for further instructions"

# Wrong — will hang in foreground-only mode
opencode --continue

Pitfall 2: Don’t Use `/exit` to Quit

Symptom: Typing /exit opens an agent selector instead of exiting.

Cause: /exit is not a valid command in OpenCode.

Fix: Use Ctrl+C or send a kill signal:

Ctrl+C

# Or from another terminal
pkill -f opencode

Pitfall 3: PATH / Binary Conflicts

Symptom: Running opencode uses the wrong version or produces unexpected behavior.

Fix: Check if you have multiple versions installed:

which -a opencode
opencode --version

If you see multiple paths, remove the extra ones or adjust your PATH order.

Pitfall 4: PATH Not Available After Install

Symptom: opencode: command not found immediately after installation.

Fix: Source your shell config or open a new terminal:

source ~/.bashrc   # or ~/.zshrc

If the install script didn’t add it automatically, add it manually:

export PATH="$HOME/.local/bin:$PATH"

Pitfall 5: npm Global Install Permission Error

Symptom: npm install -g @opencode/cli throws EACCES.

Fix: Configure npm to use a personal prefix directory:

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @opencode/cli

Pitfall 6: Binary Conflict During Upgrade

Symptom: Upgrade fails because the binary is in use.

Fix: Terminate all OpenCode processes before upgrading:

pkill opencode
opencode upgrade

Pitfall 7: File Permission Errors

Symptom: OpenCode can’t read or write files it needs.

Fix: Configure the permission section in ~/.config/opencode/opencode.json:

{
  "permission": {
    "read": {"~/projects/**": "allow"},
    "bash": "ask"
  }
}

Be specific about file patterns to maintain security while granting needed access.

Pitfall 8: curl Install Returns 404

Symptom: The curl installation script returns a 404 error.

Fix: The install script may be temporarily unavailable. Try manual installation (Method 4) or wait and retry.

Summary

OpenCode is a powerful, open-source AI coding assistant that can significantly boost your development productivity. Here’s a quick comparison of installation methods:

Method	Difficulty	Best For
Curl Script	⭐	Beginners — fully automatic, recommended
npm	⭐⭐	Node.js developers who want simple updates
Homebrew	⭐	macOS users
Manual Download	⭐⭐⭐	Specific versions, offline/air-gapped installs

After installation, the fastest path to productivity:

# 1. Install (pick one)
curl -fsSL https://opencode.ai/install | bash

# 2. Configure your AI provider
opencode providers login

# 3. Start coding
cd your-project
opencode

From there, explore the TUI shortcuts, try CLI mode for automation, configure custom agents for specialized tasks, and set up MCP servers to connect your toolchain. The more you integrate OpenCode into your workflow, the more value you’ll get from it.

Key Takeaways

4 installation methods — choose curl for simplicity, npm for Node.js ecosystems, brew for macOS, or manual for control
Two interaction modes — TUI for rich interactive sessions, CLI for scripting and automation
75+ AI providers — bring your own models or use the built-in free options
Custom agents — create specialized AI personas for different tasks
MCP integration — connect external tools and data sources
Session management — save, export, import, and share conversations
Server mode — run headless or via web interface
GitHub PR review — automated code review powered by AI

Resources

Website: https://opencode.ai
GitHub: https://github.com/sst/opencode
Config Schema: https://opencode.ai/config.json
npm Package: @opencode/cli