Moai Tool Opencode

OpenCode.ai Tool Skill

Comprehensive reference for OpenCode.ai - an open-source AI coding agent available as terminal interface, desktop application, and IDE extension.

Quick Reference

Installation:

curl -fsSL https://opencode.ai/install | bash
# or
npm install -g opencode

Start OpenCode:

opencode              # Launch TUI in current directory
opencode /path/to/dir # Launch in specific directory
opencode run "prompt" # Non-interactive mode
opencode serve        # Start headless server

Essential Commands:

• /connect - Configure API keys
• /init - Generate AGENTS.md
• /models - List available models
• /share - Share session
• /undo - Undo changes
• Tab - Switch agents
• Ctrl+P - Command palette

Configuration Files:

• ~/.config/opencode/opencode.json - Global config
• ./opencode.json - Project config
• AGENTS.md - Project instructions
• .opencode/agent/ - Custom agents
• .opencode/skill/ - Agent skills
• .opencode/tool/ - Custom tools
• .opencode/command/ - Custom commands

Documentation Index

This skill contains 32 comprehensive documentation modules organized by category.

Core (7 modules)

• Introduction - Installation, setup, primary use cases
• Configuration - JSON configuration options and merge order
• Providers - 75+ LLM providers setup
• Network - Proxy and certificate configuration
• Enterprise - SSO, central config, AI gateway
• Troubleshooting - Common issues and solutions
• Migration 1.0 - Upgrade guide

Usage (7 modules)

• TUI - Terminal interface reference
• CLI - Command-line interface
• IDE - VS Code/Cursor integration
• Zen - Curated model gateway
• Share - Session sharing
• GitHub - GitHub Actions integration
• GitLab - GitLab CI/CD integration

Configuration (14 modules)

• Tools - Built-in and custom tools
• Rules - AGENTS.md instructions
• Agents - Custom agent configuration
• Models - Model selection and variants
• Themes - Custom theme creation
• Keybinds - Keyboard shortcuts
• Commands - Custom slash commands
• Formatters - Code formatting
• Permissions - Tool approval system
• LSP Servers - Language server setup
• MCP Servers - Model Context Protocol
• ACP Support - Agent Client Protocol
• Skills - Reusable instructions
• Custom Tools - TypeScript tools

Development (4 modules)

• SDK - JavaScript/TypeScript client
• Server - HTTP API reference
• Plugins - Plugin development
• Ecosystem - Community projects

See index.md for complete navigation.

Key Concepts

Agent Architecture

Primary Agents - Main assistants you interact with directly:

• Build: Full tools enabled (default)
• Plan: Restricted, analysis-focused

Subagents - Specialized assistants invoked by primary agents:

• General: Research and multi-step tasks
• Explore: Fast codebase exploration

Configuration Hierarchy

1. Command-line flags (highest priority)
2. Environment variables
3. Project config (./opencode.json)
4. Global config (~/.config/opencode/opencode.json)
5. Built-in defaults

Tool Permission Levels

Common Patterns

Basic Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4",
  "agent": {
    "security": {
      "description": "Security auditor",
      "permission": { "edit": "deny" }
    }
  }
}

Custom Command

---
description: Review current changes
agent: plan
---
Review the following changes:
!`git diff --staged`

MCP Server Setup

{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": { "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" }
    }
  }
}

Custom Tool

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Query project database",
  args: {
    query: tool.schema.string().describe("SQL query")
  },
  async execute(args) {
    return `Executed: ${args.query}`
  }
})

Resources

• Documentation: https://opencode.ai/docs
• GitHub: https://github.com/anomalyco/opencode
• Discord: https://opencode.ai/discord

Storage Locations:

• Config: ~/.config/opencode/
• Data: ~/.local/share/opencode/
• Cache: ~/.cache/opencode/
• Logs: ~/.local/share/opencode/log/

Works Well With

• moai-lang-typescript - TypeScript development patterns
• moai-lang-python - Python development patterns
• moai-domain-backend - Backend API development
• moai-domain-frontend - Frontend development
• moai-workflow-testing - Testing workflows

Referenced Files

The following files are referenced in this skill and included for context.

modules/core/intro.md

---
source: https://opencode.ai/docs/
fetched: 2026-01-08
title: Introduction to OpenCode
---

# Introduction to OpenCode

## Overview

OpenCode is an open source AI coding agent available in multiple formats: terminal interface, desktop application, and IDE extension.

## Installation Methods

### Quick Install

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

Package Managers

Node.js (npm, Bun, pnpm, Yarn)

npm install -g opencode
# or
bun install -g opencode
# or
pnpm install -g opencode
# or
yarn global add opencode

Homebrew (macOS/Linux)

brew install opencode

Paru (Arch Linux)

paru -S opencode

Chocolatey (Windows)

choco install opencode

Scoop (Windows)

scoop install opencode

Mise

mise use -g opencode

Docker

Docker support is available for containerized environments.

Core Setup Steps

1. Prerequisites

• Modern terminal emulator (WezTerm, Alacritty, Ghostty, Kitty)
• LLM API keys

2. Configuration

Users connect via /connect command, authenticate at opencode.ai/auth, and input API credentials.

3. Project Initialization

Navigate to project directory and run opencode, then execute /init to analyze the codebase and generate AGENTS.md.

Primary Use Cases

The documentation highlights four main workflows:

Question Asking

Query codebase understanding using @ syntax for file references.

@src/main.ts What does this file do?

Feature Planning

Toggle Plan mode (Tab key) to review implementation approaches before building.

Direct Changes

Request specific modifications with detailed context.

Version Control

Undo/redo changes via /undo and /redo commands.

Additional Features

Sharing

/share command creates shareable conversation links.

Customization

• Theme selection
• Keybind configuration
• Code formatter setup
• Custom commands

Documentation

References to config, providers, and troubleshooting resources.

Best Practices

The page emphasizes providing detailed context and treating the AI agent like a junior developer for optimal results.

### modules/core/config.md

```markdown
---
source: https://opencode.ai/docs/config/
fetched: 2026-01-08
title: Configuration
---

# OpenCode Configuration Guide

## Overview

OpenCode uses JSON/JSONC config files to customize the tool's behavior across TUI, CLI, IDE, and other interfaces.

## Configuration Locations (Merge Order)

Configuration files are merged together, not replaced. Settings from the following config locations are combined:

1. **Global**: `~/.config/opencode/opencode.json`
2. **Per-project**: `opencode.json` in project root (merged with global)
3. **Custom path**: Via `OPENCODE_CONFIG` environment variable
4. **Custom directory**: Via `OPENCODE_CONFIG_DIR` environment variable

## Core Configuration Options

### Models & Providers

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-3-5",
  "provider": {
    "anthropic": {
      "timeout": 30000,
      "setCacheKey": true,
      "region": "us-east-1",
      "profile": "default",
      "endpoint": "https://api.anthropic.com"
    }
  }
}

• model: Primary model (e.g., "anthropic/claude-sonnet-4-5")
• small_model: Lightweight tasks like title generation
• provider: Provider-specific settings (timeout, setCacheKey, region, profile, endpoint)

Interface Settings

{
  "theme": "dark",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": 1.5,
    "diff_style": "unified"
  },
  "server": {
    "port": 3000,
    "hostname": "localhost",
    "mdns": true,
    "cors": true
  }
}

• theme: Visual appearance configuration
• tui: Terminal UI options (scroll_speed, scroll_acceleration, diff_style)
• server: Server settings (port, hostname, mdns, cors)

Functionality

{
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "code-review": {
      "description": "Code review specialist",
      "model": "anthropic/claude-sonnet-4",
      "prompt": "You are a code review expert..."
    }
  },
  "default_agent": "code-review",
  "command": {
    "test": {
      "description": "Run tests",
      "command": "npm test"
    }
  },
  "keybinds": {
    "submit": "ctrl+enter"
  },
  "formatter": {
    "typescript": "prettier"
  },
  "permission": {
    "write": "ask",
    "bash": "allow"
  }
}

• tools: Enable/disable tools like write, bash
• agent: Define specialized agents for specific tasks
• default_agent: Agent used when none specified
• command: Custom commands for repetitive workflows
• keybinds: Keyboard shortcuts customization
• formatter: Code formatter configuration
• permission: Tool approval requirements ("ask", "allow", etc.)

Features & Behavior

{
  "share": "manual",
  "autoupdate": true,
  "compaction": "auto",
  "watcher": {
    "ignore": ["node_modules", ".git"]
  },
  "mcp": {
    "servers": {}
  },
  "plugin": [],
  "instructions": ["AGENTS.md", ".opencode/*.md"],
  "disabled_providers": [],
  "enabled_providers": [],
  "experimental": {}
}

• share: Sharing mode ("manual", "auto", "disabled")
• autoupdate: Auto-update behavior (true/false/"notify")
• compaction: Context management (auto, prune)
• watcher: File watching ignore patterns
• mcp: Model Context Protocol server configuration
• plugin: Load custom plugins from npm or local files
• instructions: Array of instruction files/glob patterns
• disabled_providers: Blocklist of providers
• enabled_providers: Allowlist of providers
• experimental: Unstable features under development

Variable Substitution

Environment Variables

Use {env:VARIABLE_NAME} syntax:

{
  "model": "{env:OPENCODE_MODEL}"
}

File Contents

Use {file:path/to/file} syntax:

{
  "apiKey": "{file:~/.secrets/openai-key}"
}

File paths support relative (to config) and absolute paths (/ or ~).

Provider-Specific Options

Amazon Bedrock

Amazon Bedrock supports the following options:

• region: AWS region (defaults to AWS_REGION env or us-east-1)
• profile: AWS named profile
• endpoint: Custom VPC endpoint URL

Note: Bearer tokens take precedence over profile-based authentication.

{
  "provider": {
    "amazon-bedrock": {
      "region": "us-west-2",
      "profile": "production",
      "endpoint": "https://bedrock.us-west-2.amazonaws.com"
    }
  }
}

Agent Configuration

Agents can be defined inline in the config or via markdown files:

• Global: ~/.config/opencode/agent/
• Project: .opencode/agent/

Configuration includes:

• description: What the agent does
• model: Which model to use
• prompt: System prompt for the agent
• Tool restrictions

Important Notes

• The schema is defined at opencode.ai/config.json
• Experimental options are not stable. They may change or be removed without notice.
• disabled_providers takes priority over enabled_providers
• Sharing defaults to manual mode requiring explicit /share command

### modules/core/providers.md

```markdown
---
source: https://opencode.ai/docs/providers/
fetched: 2026-01-08
title: Providers
---

# OpenCode Providers Documentation

## Overview

OpenCode supports **75+ LLM providers** through the AI SDK and Models.dev, including local model execution. Setting up a provider requires two steps:

1. Add API keys via the `/connect` command (stored in `~/.local/share/opencode/auth.json`)
2. Configure the provider in your OpenCode config file

## Base URL Customization

Users can override default endpoints:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  }
}

OpenCode Zen

OpenCode Zen provides curated, tested models from the OpenCode team. Setup requires:

1. Run /connect, select opencode, visit opencode.ai/auth
2. Sign in and copy your API key
3. Use /models to view recommendations

Provider Directory

Amazon Bedrock

• Requires Model Catalog access
• Authentication via AWS credentials, profiles, or bearer tokens
• Supports VPC endpoints with custom endpoint configuration
• Priority: Bearer Token > AWS Credential Chain

{
  "provider": {
    "amazon-bedrock": {
      "region": "us-west-2",
      "profile": "production",
      "endpoint": "https://bedrock-runtime.us-west-2.amazonaws.com"
    }
  }
}

Anthropic

• Recommends Claude Pro/Max subscription
• Supports OAuth flow or manual API key entry
• Available via /connect command

{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Azure OpenAI

• Requires resource creation and model deployment
• Deployment names must match model names
• Set AZURE_RESOURCE_NAME environment variable

Note: "I'm sorry" errors may indicate content filter issues—switch from DefaultV2 to Default.

{
  "provider": {
    "azure-openai": {
      "options": {
        "resourceName": "{env:AZURE_RESOURCE_NAME}",
        "apiKey": "{env:AZURE_OPENAI_API_KEY}"
      }
    }
  }
}

Google Vertex AI

• Requires Google Cloud project with Vertex AI API enabled
• Key environment variables: GOOGLE_CLOUD_PROJECT, VERTEX_LOCATION
• Supports service account authentication
• "Global" region recommended for availability

{
  "provider": {
    "google-vertex": {
      "options": {
        "project": "{env:GOOGLE_CLOUD_PROJECT}",
        "location": "us-central1"
      }
    }
  }
}

Local Models (Ollama, LM Studio, llama.cpp)

Custom provider configuration example:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

Helicone

Observability platform supporting 17+ providers with automatic routing. Optional custom configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helicone": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helicone",
      "options": {
        "baseURL": "https://ai-gateway.helicone.ai",
        "headers": {
          "Helicone-Cache-Enabled": "true",
          "Helicone-User-Id": "opencode"
        }
      }
    }
  }
}

Common headers include:

• Helicone-Cache-Enabled
• Helicone-User-Id
• Helicone-Property-[Name]
• Helicone-Prompt-Id
• Helicone-Session-Id

OpenRouter & ZenMux

Support custom model additions via config:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "somecoolnewmodel": {}
      }
    }
  }
}

OpenRouter supports provider routing:

{
  "provider": {
    "openrouter": {
      "models": {
        "anthropic/claude-sonnet-4": {
          "options": {
            "order": ["baseten"],
            "allow_fallbacks": false
          }
        }
      }
    }
  }
}

Vercel AI Gateway

{
  "provider": {
    "vercel": {
      "models": {
        "anthropic/claude-sonnet-4": {
          "options": {
            "order": ["anthropic", "vertex"]
          }
        }
      }
    }
  }
}

Routing options: order, only, zeroDataRetention.

Custom Provider (OpenAI-Compatible)

1. Run /connect and select "Other"
2. Enter unique provider ID
3. Enter API key
4. Configure in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Display Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:CUSTOM_API_KEY}",
        "headers": {
          "Authorization": "Bearer token"
        }
      },
      "models": {
        "model-id": {
          "name": "Display Name",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  }
}

Key options: baseURL, apiKey, headers, and model limit (context/output tokens).

Additional Providers Listed

• Amazon Bedrock
• Anthropic
• Azure OpenAI
• Azure Cognitive Services
• Baseten
• Cerebras
• Cloudflare AI Gateway
• Cortecs
• DeepSeek
• Deep Infra
• Fireworks AI
• GitHub Copilot
• Google Vertex AI
• Groq
• Hugging Face
• Helicone
• llama.cpp
• IO.NET
• LM Studio
• Moonshot AI
• MiniMax
• Nebius Token Factory
• Ollama
• Ollama Cloud
• OpenAI
• OpenRouter
• SAP AI Core
• OVHcloud AI Endpoints
• Together AI
• Venice AI
• Vercel AI Gateway
• xAI
• Z.AI
• ZenMux

Troubleshooting

• Verify credentials: opencode auth list
• Confirm provider ID matches across /connect and config
• Validate npm package (use provider-specific or @ai-sdk/openai-compatible)
• Check baseURL correctness

### modules/core/network.md

```markdown
---
source: https://opencode.ai/docs/network/
fetched: 2026-01-08
title: Network Configuration
---

# Network Configuration Guide

OpenCode provides enterprise-grade networking support through proxy and certificate management.

## Proxy Setup

OpenCode recognizes standard proxy environment variables for routing traffic through corporate proxies:

```bash
export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

Critical requirement: The NO_PROXY variable must exclude localhost addresses. The TUI relies on local HTTP server communication, and proxying this traffic creates routing loops.

Authentication

For credential-protected proxies, embed credentials directly in the proxy URL:

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

Security Best Practices

The documentation advises against hardcoding passwords, recommending:

• Environment variables
• Secure credential management systems

Advanced Authentication

For advanced authentication schemes like NTLM or Kerberos, using an LLM Gateway with native support is suggested.

Custom Certificates

Enterprise environments using custom certificate authorities can configure OpenCode to trust them:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

This setting applies to both proxy connections and direct API communications.

Server Configuration

OpenCode supports configurable server ports and hostnames via CLI flags:

opencode --port 3000 --hostname localhost

Complete Example

# Proxy configuration
export HTTPS_PROXY=https://proxy.corporate.com:8080
export HTTP_PROXY=http://proxy.corporate.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.corp

# Custom CA certificate
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corporate-ca.pem

# Start OpenCode
opencode

### modules/core/enterprise.md

```markdown
---
source: https://opencode.ai/docs/enterprise/
fetched: 2026-01-08
title: Enterprise
---

# OpenCode Enterprise

## Overview

OpenCode Enterprise enables organizations to keep code and data within their own infrastructure through centralized configuration, SSO integration, and internal AI gateway support.

## Trial & Data Security

**Key Statement:** "OpenCode does not store any of your code or context data."

All processing occurs locally or via direct API calls to the provider. The only exception is the optional `/share` feature, which sends conversations to opencode.ai's CDN.

### Recommended Trial Configuration

```json
{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled"
}

Code Ownership

Users retain all rights to code produced by OpenCode with no licensing restrictions.

Enterprise Features

Central Config

Single organizational configuration managing SSO and AI gateway access.

SSO Integration

Authentication through existing identity management systems to obtain gateway credentials.

Internal AI Gateway

Route all requests exclusively through approved organizational infrastructure.

Self-Hosting

Currently on roadmap; option to host share pages on internal infrastructure.

Pricing Model

• Per-seat licensing
• No token charges if organizations maintain their own LLM gateway
• Custom quotes available upon contact

Private NPM Registry Support

Organizations using private registries (JFrog Artifactory, Nexus, etc.) must authenticate developers before running OpenCode:

npm login --registry=https://your-company.jfrog.io/api/npm/npm-virtual/

Important Requirement: "You must be logged into the private registry before running OpenCode."

Contact

Organizations interested in implementation should email contact@anoma.ly for pricing and deployment discussions.

### modules/core/troubleshooting.md

```markdown
---
source: https://opencode.ai/docs/troubleshooting/
fetched: 2026-01-08
title: Troubleshooting
---

# OpenCode Troubleshooting Guide

## Overview

OpenCode provides debugging tools through logs and local storage to help resolve issues.

## Logs Location

Log files are stored at:

| Platform | Path |
|----------|------|
| macOS/Linux | `~/.local/share/opencode/log/` |
| Windows | `%USERPROFILE%\.local\share\opencode\log\` |

Files use timestamp naming (e.g., `2025-01-09T123456.log`) with the 10 most recent retained.

### Enable Detailed Logging

```bash
opencode --log-level DEBUG

Storage Location

Application data resides at:

Contents

• auth.json - API keys and OAuth tokens
• log/ - Application logs
• project/ - Session and message data
  • ./<project-slug>/storage/ for Git repos
  • ./global/storage/ otherwise

Getting Help

GitHub Issues

Report bugs at github.com/anomalyco/opencode/issues

Discord Community

Real-time assistance available at opencode.ai/discord

Common Issues & Solutions

Won't Start

• Check logs
• Run with --print-logs
• Verify latest version via opencode upgrade

opencode --print-logs
opencode upgrade

Authentication Problems

• Use /connect command in TUI
• Validate API keys
• Confirm network access to provider APIs

Model Unavailable

• Confirm provider authentication
• Verify correct model naming format (<providerId>/<modelId>)
• Use opencode models command to check access

opencode models

ProviderInitError

• Verify provider setup
• Clear configuration via rm -rf ~/.local/share/opencode
• Re-authenticate

rm -rf ~/.local/share/opencode
opencode
/connect

API Call Errors

• Clear provider cache with rm -rf ~/.cache/opencode
• Restart to reinstall latest packages

rm -rf ~/.cache/opencode
opencode

Linux Copy/Paste Issues

Install clipboard utilities based on your environment:

# For X11
sudo apt install xclip

# For Wayland
sudo apt install wl-clipboard

### modules/core/migration-1.0.md

```markdown
---
source: https://opencode.ai/docs/1-0/
fetched: 2026-01-08
title: Migrating to 1.0
---

# OpenCode 1.0 Migration Guide

## Key Overview

OpenCode 1.0 represents "a complete rewrite of the TUI," transitioning from a Go/Bubbletea framework to an in-house solution built with Zig and SolidJS. The new version maintains compatibility with the existing OpenCode server while improving performance and capabilities.

## Upgrade Instructions

### Manual Upgrade

```bash
opencode upgrade 1.0.0

Revert to Previous Version

opencode upgrade 0.15.31

Note: Some older versions automatically fetch the latest release.

Notable UX Improvements

Command Bar

The interface now includes "a command bar which almost everything flows through," accessible via Ctrl+P.

Session History

Session history display has been simplified to focus on edit and bash tool details.

Session Sidebar

A toggleable session sidebar provides additional context.

Breaking Changes

Renamed Keybinds

Four keybinds were renamed:

Removed Keybinds

Twelve keybinds were removed entirely, including functionality for:

• Layout toggling
• File operations
• Help display
• Thinking block management

Feedback

The documentation encourages users to report missing features via GitHub issues.

Technical Details

Framework Changes

• Previous: Go/Bubbletea
• Current: Zig and SolidJS (in-house solution)

Compatibility

The new version maintains compatibility with the existing OpenCode server.

Performance

The rewrite focuses on improving performance and capabilities.

### modules/usage/tui.md

```markdown
---
source: https://opencode.ai/docs/tui/
fetched: 2026-01-08
title: Terminal User Interface (TUI)
---

# OpenCode TUI Documentation

## Overview

OpenCode provides an interactive terminal interface (TUI) for working on projects with an LLM. Launch it by running `opencode` in your project directory or specify a path:

```bash
opencode
# or
opencode /path/to/project

File References

Users can reference files in messages using @ to perform fuzzy file searching within the current working directory.

Example:

How is auth handled in @packages/functions/src/api/index.ts?

The file content is automatically included in conversations.

Bash Commands

Messages beginning with ! execute shell commands. The command output is then added to the conversation as a tool result.

Example:

!npm test

Commands (Slash Commands)

All commands use / prefix and most include ctrl+x keybind shortcuts (ctrl+x is the default leader key):

Editor Setup

The EDITOR environment variable controls which editor opens for /editor and /export commands.

Linux/macOS

export EDITOR=nano
export EDITOR=vim
export EDITOR="code --wait"

Windows CMD

set EDITOR=notepad
set EDITOR="code --wait"

Windows PowerShell

$env:EDITOR = "notepad"
$env:EDITOR = "code --wait"

Popular Editors

Note: Some editors like VS Code need to be started with the --wait flag to block until closed.

Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

Options

Customization

Users can customize TUI view settings through the command palette (ctrl+x h or /help). Settings persist across restarts.

Username Display

Toggle whether your username appears in chat messages through the command palette by searching "username" or "hide username."

### modules/usage/cli.md

```markdown
---
source: https://opencode.ai/docs/cli/
fetched: 2026-01-08
title: Command Line Interface (CLI)
---

# OpenCode CLI Documentation

## Overview

OpenCode is a CLI tool that defaults to launching a terminal user interface (TUI) when run without arguments. It supports both interactive and programmatic modes, allowing users to interact with the system through various commands and flags.

## Basic Usage

```bash
# Launch TUI in current directory
opencode

# Launch TUI in specific directory
opencode /path/to/project

# Run non-interactive with a prompt
opencode run "Your prompt here"

Global Flags

Core Commands

Agent Management

Create, list, and manage custom agents with configurable system prompts and tool configurations.

opencode agent list
opencode agent create my-agent

Authentication

Handle credentials across multiple providers.

opencode auth login
opencode auth list
opencode auth logout

Credentials are stored in ~/.local/share/opencode/auth.json.

Session Control

List, export, and import session data in JSON format.

opencode session list
opencode session export <session-id>
opencode session import <file.json>

Supports OpenCode share URLs for importing sessions.

Model Operations

Display available models from configured providers in provider/model format.

opencode models
opencode models --refresh  # Refresh cache

Server Modes

Headless HTTP API Server:

opencode serve

HTTP Server with Web Browser Interface:

opencode web

Agent Client Protocol Server (stdin/stdout):

opencode acp

GitHub Integration

Install workflows and run agents within GitHub Actions environments.

opencode github install
opencode github run

MCP Server Management

Add, list, and authenticate Model Context Protocol servers with OAuth support.

opencode mcp add <server-name>
opencode mcp list
opencode mcp auth <server-name>

Non-Interactive Mode

The opencode run command enables non-interactive execution:

opencode run "Your prompt here"

"Run opencode in non-interactive mode by passing a prompt directly."

Environment Variables

Advanced Features

Attachment Capability

Connect to running servers to avoid cold boot times on subsequent invocations.

Experimental Flags

Advanced features may be available through experimental flags. Check --help for current options.

Examples

# Start TUI with debug logging
opencode --log-level DEBUG

# Run a quick prompt
opencode run "Explain the authentication flow in this codebase"

# Start headless server on custom port
opencode serve --port 8080

# List all available models
opencode models

# Export current session
opencode session export my-session > session.json

### modules/usage/ide.md

```markdown
---
source: https://opencode.ai/docs/ide/
fetched: 2026-01-08
title: IDE Integration
---

# OpenCode IDE Documentation

## Overview

This documentation covers the OpenCode extension for VS Code, Cursor, and other IDEs that support terminal integration.

## Keyboard Shortcuts

| Action | macOS | Windows/Linux |
|--------|-------|---------------|
| Quick launch | `Cmd+Esc` | `Ctrl+Esc` |
| New session | `Cmd+Shift+Esc` | `Ctrl+Shift+Esc` |
| Insert file reference | `Cmd+Option+K` | `Alt+Ctrl+K` |

### File References

The file reference shortcut enables quick insertion like `@File#L37-42`. The tool automatically shares current selection or active tab with OpenCode.

## Installation

### Automatic Installation

The extension installs automatically when running the `opencode` command in VS Code's integrated terminal.

### Manual Installation

1. Open the Extension Marketplace in your IDE
2. Search for "OpenCode"
3. Click Install

## Supported IDEs

- VS Code
- Cursor
- Windsurf
- Codium

## Troubleshooting

If automatic installation fails:

1. **Run in integrated terminal:** Run `opencode` specifically in the integrated terminal (not an external terminal)

2. **Verify CLI tools:** Ensure IDE CLI tools are installed:
   - `code` (VS Code)
   - `cursor` (Cursor)
   - `windsurf` (Windsurf)
   - `codium` (Codium)

3. **Install shell commands:** Use command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`) to install shell commands in PATH

4. **Check permissions:** Confirm VS Code extension installation permissions are enabled

## Editor Configuration

For using custom editors with `/editor` or `/export` commands, set the `EDITOR` environment variable:

```bash
export EDITOR="code --wait"

The --wait flag ensures the editor blocks until the file is closed.

Usage Tips

• Use file references to quickly share code context
• The extension automatically detects active selections
• Works with multiple IDE instances simultaneously

### modules/usage/zen.md

```markdown
---
source: https://opencode.ai/docs/zen/
fetched: 2026-01-08
title: OpenCode Zen
---

# OpenCode Zen Documentation

## Overview

OpenCode Zen is "a list of tested and verified models provided by the OpenCode team." It operates as an optional AI gateway offering curated models vetted for coding agent performance.

## Getting Started

### Authentication

1. Visit OpenCode Zen and authenticate
2. Add billing details
3. Retrieve your API key
4. Connect via the `/connect` command in the TUI

```bash
opencode
/connect
# Select "opencode"
# Enter your API key

Available Models

The platform provides access to multiple model families:

Premium Models

• GPT 5 series
• Claude variants (Sonnet, Haiku, Opus)
• Gemini options

Open Source Models

• Qwen3
• Kimi

Free Models (Beta)

• Grok Code
• GLM 4.7
• MiniMax M2.1
• Big Pickle

Note: Free models are available during beta periods.

Pricing Structure

Pay-as-you-go model charging per 1M tokens:

Exact pricing varies by model.

Team Features

Workspaces

Workspaces support role-based access:

Admin Controls

Admins can:

• Disable specific models
• Set spending limits per team member
• Manage workspace billing

Bring Your Own Key (BYOK)

Users can integrate personal API keys while accessing other Zen models:

1. Add your OpenAI or Anthropic API key
2. Direct billing goes to your provider account
3. Access other Zen models with Zen billing

Privacy & Data Handling

Data Retention Policies

Hosting Location

All models are hosted in the US.

Configuration

To use Zen models in your config:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/claude-sonnet-4"
}

Best Practices

1. Start with recommended models from /models
2. Monitor usage through the Zen dashboard
3. Set spending limits for team members
4. Review data retention policies for sensitive projects

### modules/usage/share.md

```markdown
---
source: https://opencode.ai/docs/share/
fetched: 2026-01-08
title: Share Feature
---

# OpenCode Share Feature Documentation

## Overview

OpenCode enables users to create public links for conversations, facilitating collaboration.

**Important:** "Shared conversations are publicly accessible to anyone with the link."

## How It Works

The sharing mechanism operates in three steps:

1. Generates a unique public URL for the session
2. Synchronizes conversation history to OpenCode servers
3. Makes content accessible via the format `opncd.ai/s/<share-id>`

## Sharing Modes

### Manual (Default)

Users must explicitly invoke `/share` to generate a shareable URL copied to clipboard.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

Auto-Share

Enabling automatic sharing shares all new conversations automatically:

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

Disabled

Completely prevents sharing functionality:

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

Un-sharing

The /unshare command removes public access and deletes associated conversation data.

/unshare

Privacy Considerations

Data Retention

Shared conversations persist until explicitly unshared, including:

• Full conversation history
• Metadata

Key Recommendations

1. Review before sharing: Check content for sensitive information
2. Avoid sensitive data: Do no

…(truncated)