# Opencode

> Guide for opencode CLI and web server — non-interactive mode, headless server, sessions, model config, and all CLI subcommands.

- Skill: `dimitrigilbert/opencode` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dimitrigilbert/opencode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dimitrigilbert/opencode/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dimitrigilbert (https://skillmd.com/u/dimitrigilbert)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dimitrigilbert/opencode

---


# OpenCode CLI & Web Server Guide

Load this skill when the user asks about using opencode as a tool — CLI commands, non-interactive mode, web server, sessions, models, or any `opencode <command>` usage.

## Installation

```bash
curl -fsSL https://opencode.ai/install | bash
# Or: npm install -g opencode-ai
# Or: brew install anomalyco/tap/opencode
```

## Global Options

All commands support: `--help`, `--version`, `--print-logs`, `--log-level <DEBUG|INFO|WARN|ERROR>`, `--pure` (disable plugins)

Global flags for TUI/server modes: `-m <provider/model>`, `-c` / `--continue` (resume last session), `-s <id>` / `--session` (resume specific session), `--fork` (copy on resume), `--agent <name>`, `--prompt <text>`

## Non-Interactive Mode: `opencode run`

Execute opencode without launching the TUI. Ideal for scripting, CI/CD, and automation.

```bash
# Basic usage
opencode run "Explain async/await in TypeScript"

# With specific model
opencode run -m anthropic/claude-sonnet-4-20250514 "Refactor this function"

# Attach files to the prompt
opencode run -f src/index.ts "Explain this file"

# Continue last session
opencode run -c "Now add error handling"

# Fork a session (creates copy)
opencode run -c --fork "Try a different approach"

# Output raw JSON events (for piping/processing)
opencode run --format json "List all TODO comments"

# Share the session after completion
opencode run --share "Generate a README"
```

### `run` Flags

| Flag | Description |
|------|-------------|
| `-m, --model <provider/model>` | Model to use |
| `--agent <name>` | Agent to use |
| `-c, --continue` | Continue last session |
| `-s, --session <id>` | Resume specific session |
| `--fork` | Fork session before continuing |
| `--share` | Share session after completion |
| `--format <default\|json>` | Output format (default: formatted) |
| `-f, --file <path>` | Attach file(s) to message (repeatable) |
| `--title <text>` | Title for the session |
| `--attach <url>` | Attach to running server (e.g., http://localhost:4096) |
| `-p, --password <pw>` | Basic auth password (env: OPENCODE_SERVER_PASSWORD) |
| `-u, --username <user>` | Basic auth username (default: opencode) |
| `--dir <path>` | Working directory |
| `--port <num>` | Local server port (random if omitted) |
| `--variant <level>` | Model reasoning effort (e.g., high, max, minimal) |
| `--thinking` | Show thinking blocks |
| `-i, --interactive` | Run in direct interactive split-footer mode |
| `--dangerously-skip-permissions` | Auto-approve non-denied permissions |
| `--command <cmd>` | Run a slash command instead of a message |

### Attaching `run` to a Server

Avoid MCP cold boot by attaching to a running server:

```bash
# Terminal 1: start server
opencode serve

# Terminal 2: run commands against it
opencode run --attach http://localhost:4096 "Fix the lint errors"
```

## Headless Server: `opencode serve`

Start a headless server without TUI. Other clients (run --attach, web, attach) connect to it.

```bash
# Start with defaults (random port, localhost)
opencode serve

# Specify port
opencode serve --port 4096

# Expose on all interfaces
opencode serve --hostname 0.0.0.0 --port 4096

# Enable mDNS discovery
opencode serve --mdns --port 4096

# Allow CORS for specific origins
opencode serve --cors http://localhost:5173 --port 4096
```

### `serve` Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--port <num>` | 0 (random) | Port to listen on |
| `--hostname <addr>` | 127.0.0.1 | Bind address |
| `--mdns` | false | Enable mDNS service discovery |
| `--mdns-domain <name>` | opencode.local | Custom mDNS domain |
| `--cors <origin>` | [] | Additional CORS domains (repeatable) |

### Server REST API

The server exposes a REST API at the bound address. Key endpoints:

- `GET /app` — Application details
- `POST /app/init` — Initialize application
- `GET /config/providers` — List configured providers
- `GET /mode` — Available modes
- `GET /session` — List sessions
- `POST /session/init` — Initialize session
- `POST /session/summarize` — Summarize session
- `POST /session/abort` — Abort running session
- `DELETE /session/delete` — Delete session
- `GET /file/read?path=<path>` — Read file content
- `GET /file/status` — Modified files status
- `GET /find/file` — Search files
- `GET /find/symbol` — Search symbols
- `GET /find` — Search text

Authentication: Use `-u` / `-p` flags or `OPENCODE_SERVER_USERNAME` / `OPENCODE_SERVER_PASSWORD` env vars.

## Web Interface: `opencode web`

Start server and open the web UI in a browser. Same flags as `serve`.

```bash
opencode web
opencode web --port 4096 --hostname 0.0.0.0
opencode web --cors http://localhost:5173
```

You can attach a TUI to the same web server:

```bash
# Terminal 1
opencode web --port 4096

# Terminal 2
opencode attach http://localhost:4096
```

## Attach to Server: `opencode attach`

Connect a TUI to a running `serve` or `web` instance.

```bash
opencode attach http://localhost:4096

# With session resume
opencode attach http://localhost:4096 -c

# With specific session
opencode attach http://localhost:4096 -s <session-id>

# With auth
opencode attach http://localhost:4096 -u opencode -p secretpassword
```

| Flag | Description |
|------|-------------|
| `--dir <path>` | Working directory |
| `-c, --continue` | Continue last session |
| `-s, --session <id>` | Resume specific session |
| `--fork` | Fork on resume |
| `-p, --password <pw>` | Auth password |
| `-u, --username <user>` | Auth username |

## ACP Server: `opencode acp`

Start an Agent Client Protocol server (same flags as `serve` plus `--cwd`).

```bash
opencode acp --port 4096 --cwd /path/to/project
```

## Session Management

```bash
# List sessions
opencode session list
opencode session list -n 10 --format json

# Delete a session
opencode session delete <session-id>

# Export session as JSON
opencode export <session-id>
opencode export <session-id> --sanitize  # redact sensitive data

# Import session from file or share URL
opencode import session.json
opencode import https://opencode.ai/share/abc123
```

## Models & Providers

```bash
# List all available models
opencode models

# Filter by provider
opencode models anthropic

# Verbose (includes cost info)
opencode models --verbose

# Refresh model cache
opencode models --refresh

# Manage providers
opencode providers list
opencode providers login
opencode providers logout
```

## PR Workflow: `opencode pr`

Fetch a GitHub PR branch, checkout, and open opencode:

```bash
opencode pr 42
```

## GitHub Agent

```bash
opencode github install        # Install GitHub agent
opencode github run            # Run the agent
opencode github run --event '{"type":"issues","action":"opened",...}'
opencode github run --token github_pat_...
```

## MCP Servers

```bash
opencode mcp add               # Add an MCP server
opencode mcp list              # List servers and status
opencode mcp auth [name]       # Authenticate OAuth MCP server
opencode mcp logout [name]     # Remove OAuth credentials
opencode mcp debug <name>      # Debug OAuth connection
```

## Agent Management

```bash
# List agents
opencode agent list

# Create agent
opencode agent create --description "Review code" --mode subagent --tools "read,grep,glob"

# Create with model
opencode agent create -m anthropic/claude-sonnet-4-20250514 --mode primary

# Create at specific path
opencode agent create --path .opencode/agents/reviewer.md
```

| `create` Flag | Description |
|---------------|-------------|
| `--path <dir>` | Output directory |
| `--description <text>` | What the agent does |
| `--mode <all\|primary\|subagent>` | Agent mode |
| `--tools <list>` | Comma-separated permissions: bash,read,edit,glob,grep,webfetch,task,todowrite,websearch,lsp,skill |
| `-m <model>` | Model in provider/model format |

## Stats & Debugging

```bash
# Token usage and costs
opencode stats
opencode stats --days 7 --models --project myproject
opencode stats --tools 10

# Debug tools
opencode debug config           # Show resolved config
opencode debug paths            # Global paths (data, config, cache, state)
opencode debug info             # Debug information
opencode debug skill            # List available skills
opencode debug agent <name>     # Show agent config details
opencode debug startup          # Startup timing
opencode debug lsp              # LSP debugging
opencode debug rg               # Ripgrep debugging
opencode debug file             # File system debugging
opencode debug scrap            # List all known projects
opencode debug snapshot         # Snapshot debugging
```

## Database Tools

```bash
opencode db                     # Interactive SQLite shell
opencode db "SELECT * FROM session LIMIT 5"  # Run query
opencode db path                # Print database path
opencode db migrate             # Migrate JSON data to SQLite
opencode db --format json "SELECT count(*) FROM message"
```

## Plugins & Extensions

```bash
# Install plugin
opencode plugin <npm-module>
opencode plugin <npm-module> --global
opencode plugin <npm-module> --force  # Replace existing version
```

## Upgrade & Uninstall

```bash
# Upgrade
opencode upgrade
opencode upgrade 0.1.48
opencode upgrade --method curl

# Uninstall
opencode uninstall --dry-run       # Preview what gets removed
opencode uninstall -c -d -f        # Remove but keep config and data
```

## Shell Completion

```bash
opencode completion  # Generate completion script (bash/zsh/fish)
```

## Configuration

### Config Files

- **Project**: `.opencode/opencode.json`
- **Global**: `~/.config/opencode/config.json`

### Server Config (opencode.json)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENCODE_AUTO_SHARE` | Auto-share sessions |
| `OPENCODE_CONFIG` | Custom config path |
| `OPENCODE_DISABLE_CLAUDE_CODE` | Disable Claude Code compat |
| `OPENCODE_SERVER_PASSWORD` | Default auth password |
| `OPENCODE_SERVER_USERNAME` | Default auth username |

## TUI Quick Reference

When using `opencode` interactively (default, no subcommand):

| Key/Command | Action |
|-------------|--------|
| `Tab` | Switch Build/Plan mode |
| `Ctrl+X` | Leader key for shortcuts |
| `/help` | Show help |
| `/init` | Create AGENTS.md |
| `/connect` | Configure AI provider |
| `/new` | New session |
| `/sessions` | List sessions |
| `/models` | Switch model |
| `/undo` / `/redo` | Git-based undo/redo |
| `/share` / `/unshare` | Share/unshare session |
| `/compact` | Compact context |
| `/details` | Show details |
| `/thinking` | Toggle thinking |
| `/export` | Export session |
| `@file` | Fuzzy file reference |
| `!command` | Execute shell command |