OpenCode: Quick Reference, Migration & Metrics

API Key Setup (dsec)

API keys are stored in the dsec encrypted secrets system under d000 dev/app alongside other application secrets.

Step 1: Generate API Keys

Visit each dashboard and generate an API key:

Provider Dashboard URL Key Prefix

Anthropic (Claude)

console.anthropic.com/settings/keys

sk-ant-…​

OpenAI (GPT)

platform.openai.com/api-keys

sk-…​

DeepSeek

platform.deepseek.com/api_keys

sk-…​

Google (Gemini)

aistudio.google.com/apikey

AI…​

Step 2: Add to dsec

dsec edit d000 dev/app

Paste this section at the bottom of the file, fill in the keys:

# ============================================================================
# === AI / LLM Provider API Keys ===
# ============================================================================

# --- Anthropic (Claude) ---
# Dashboard: https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=

# --- OpenAI (GPT) ---
# Dashboard: https://platform.openai.com/api-keys
OPENAI_API_KEY=

# --- DeepSeek ---
# Dashboard: https://platform.deepseek.com/api_keys
DEEPSEEK_API_KEY=

# --- Google (Gemini) ---
# Dashboard: https://aistudio.google.com/apikey
GOOGLE_GENERATIVE_AI_API_KEY=

# --- OpenCode Feature Flags ---
OPENCODE_EXPERIMENTAL_LSP_TOOL=true

Save and exit. dsec auto-encrypts the file.

Step 3: Load and Launch

# Load secrets into current shell
ds d000 dev/app
# Verify keys are loaded (shows var names, not values)
env | grep -E "ANTHROPIC|OPENAI|DEEPSEEK|GOOGLE_GENERATIVE" | awk -F= '{print $1, "=", substr($2,1,8) "..."}'
# Launch OpenCode
opencode

Step 4: Authenticate GitHub Copilot

GitHub Copilot uses device login, not an API key. Inside OpenCode TUI:

/connect
# Select GitHub Copilot
# Browser opens → enter device code → authorize
# Token cached for future sessions

Step 5: Verify All Providers

Inside OpenCode TUI:

# List available models across all providers
/models

# Switch model to test each provider
Ctrl+X → M    # Open model picker
# Select anthropic/claude-sonnet-4-6 → send a test message
# Select openai/gpt-4.1 → send a test message
# Select deepseek/deepseek-chat → send a test message
# Select google/gemini-2.5-flash → send a test message

Provider Status Checklist

Provider Auth Method Status

Anthropic

ANTHROPIC_API_KEY env var

[ ] Key generated, loaded via dsec

OpenAI

OPENAI_API_KEY env var

[ ] Key generated, loaded via dsec

DeepSeek

DEEPSEEK_API_KEY env var

[ ] Key generated, loaded via dsec

Google Gemini

GOOGLE_GENERATIVE_AI_API_KEY env var

[ ] Key generated, loaded via dsec

GitHub Copilot

/connect device login

[ ] Authenticated via browser

Ollama (local)

N/A (not installed)

[ ] Skipped — uncomment in opencode.jsonc when installed

Daily Workflow

# Start of session: load secrets + launch
ds d000 dev/app && opencode

# Or alias in ~/.zshrc:
# alias oc='ds d000 dev/app && opencode'

Troubleshooting

Problem Fix

"No API key" error

Run ds d000 dev/app before launching OpenCode

Provider not showing in /models

Check env | grep API_KEY — key must be exported

DeepSeek connection refused

Verify baseURL in opencode.jsonc is api.deepseek.com

Copilot models not available

Re-run /connect — token may have expired

Wrong model on startup

Check "model" in opencode.jsonc — should be anthropic/claude-sonnet-4-6

Quick Reference

Installation

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

# Or via package manager (Arch)
paru -S opencode-bin

# Or via npm
npm install -g opencode

# Verify
opencode --version

Daily Usage

# Start OpenCode in current directory
opencode

# Start with specific model
opencode --model ollama/qwen-coder-14b

# Start in Plan mode (read-only)
opencode --mode plan

# Resume previous session
opencode --resume

# Non-interactive query
opencode -p "explain this function"

# Generate AGENTS.md for new project
opencode /init

In-Session Commands

# Skills
/deploy                          # Push and rebuild docs
/deploy "docs: New runbook"      # With commit message
/worklog                         # Create today's worklog
/session                         # Create session log

# Built-in commands
/undo                            # Undo last file change
/redo                            # Redo last undo
/share                           # Share session link
/models                          # List available models
/theme                           # Switch theme
/help                            # Show help

# Agent dispatch
@general "complex multi-step task"
@explore "find all AsciiDoc partials"
@adoc-linter "check this component"

Keybinding Cheatsheet

Key Action

Tab

Toggle Build/Plan mode

Ctrl+X → M

Model picker

Ctrl+X → A

Agent picker

Ctrl+X → N

New session

Ctrl+X → S

Share session

Ctrl+X → H

Session history

Ctrl+X → Q

Quit

Ctrl+Z

Undo

Ctrl+Y

Redo

Provider Quick Switch

# In model picker (Ctrl+X → M), select:
ollama/qwen-coder-14b           # Free, local, fast
deepseek/deepseek-chat           # Cheap cloud coder
copilot/gpt-4.1                  # Existing subscription
openai/gpt-4.1                   # Second opinion
google/gemini-2.5-pro            # Large context
anthropic/claude-sonnet           # Best reasoning

MCP Server Management

opencode mcp list                # List configured servers
opencode mcp auth <server>       # Authenticate
opencode mcp debug <server>      # Debug connection
opencode mcp logout <server>     # Logout

Environment Variables

# Provider API keys
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
export DEEPSEEK_API_KEY="..."
export GOOGLE_GENERATIVE_AI_API_KEY="..."

# OpenCode config
export OPENCODE_CONFIG="/path/to/custom/config.json"
export OPENCODE_CONFIG_CONTENT='{"provider":{"ollama":{...}}}'

File Locations

File Purpose

~/.config/opencode/opencode.json

Global config (providers, agents, permissions)

~/.config/opencode/tui.json

TUI config (theme, keybindings)

<repo>/opencode.json

Project config (merges with global)

<repo>/AGENTS.md

Project instructions

<repo>/.opencode/

Project agents, commands, modes, plugins, skills, themes

~/.config/opencode/agents/

Global agents

~/.config/opencode/skills/

Global skills

~/.config/opencode/themes/

Global custom themes

~/.config/opencode/plugins/

Global plugins

CLI Reference

Core Commands

Command Purpose

opencode

Start TUI (default — interactive terminal UI)

opencode run [message]

Non-interactive mode — send a prompt, get a response, exit

opencode serve

Start headless HTTP server (no TUI, API only)

opencode web

Start server + web interface

opencode attach [url]

Attach TUI to a running OpenCode server (remote control)

Agent Management

Command Purpose

opencode agent create

Interactive wizard to create a new agent markdown file

opencode agent list

List all configured agents

Authentication

Command Purpose

opencode auth login

Authenticate with a provider (stores in ~/.local/share/opencode/auth.json)

opencode auth list

List stored credentials

opencode auth logout

Remove stored credentials

MCP Server Management

Command Purpose

opencode mcp add

Add a new MCP server interactively

opencode mcp list

List all configured MCP servers and auth status

opencode mcp auth <server>

Authenticate with an MCP server (OAuth flow)

opencode mcp logout <server>

Remove stored MCP credentials

opencode mcp debug <server>

Debug MCP connection issues

Session Management

Command Purpose

opencode session list

List all sessions

opencode export [sessionID]

Export session as JSON

opencode import <file>

Import session from JSON file or URL

opencode stats

Show token usage and cost statistics

Model Management

Command Purpose

opencode models

List all available models across configured providers

opencode models [provider]

List models for a specific provider

GitHub Integration

Command Purpose

opencode github install

Install GitHub agent for CI/CD

opencode github run

Run GitHub agent

Maintenance

Command Purpose

opencode upgrade [target]

Update OpenCode to latest (or specified) version

opencode uninstall

Remove OpenCode completely

opencode acp

Start Agent Client Protocol server (Zed, JetBrains, Neovim integration)

Global Flags

Flag Purpose

--help, -h

Show help

--version, -v

Show version

--print-logs

Print logs to stdout

--log-level

Set log level (debug, info, warn, error)

--model, -m

Override model for this session

--config

Override config file path

--permission

Override permission mode (allow, ask, deny)

Non-Interactive Mode Examples

# Quick query
opencode run "explain the main function in src/index.ts"

# With specific model
opencode run -m ollama/qwen-coder-14b "fix the type error in utils.py"

# Pipe input
echo "review this code" | opencode run

# With permissive mode (auto-approve everything)
opencode run --permission allow "add error handling to all API endpoints"

Environment Variables (47)

OpenCode supports 47 environment variables for configuration, debugging, and feature flags.

Configuration Overrides

Variable Purpose

OPENCODE_CONFIG

Path to custom config file (overrides global)

OPENCODE_TUI_CONFIG

Path to custom TUI config file

OPENCODE_CONFIG_DIR

Override config directory (default: ~/.config/opencode/)

OPENCODE_CONFIG_CONTENT

Inline JSON config (highest priority override)

OPENCODE_PERMISSION

Override all permissions (allow, ask, or deny)

OPENCODE_MODELS_URL

Custom URL for model registry

OPENCODE_CLIENT

Client identifier string

Server & Auth

Variable Purpose

OPENCODE_SERVER_PASSWORD

Server authentication password

OPENCODE_SERVER_USERNAME

Server authentication username

Feature Toggles

Variable Purpose

OPENCODE_ENABLE_EXA

Enable web search via Exa AI (set to any truthy value)

OPENCODE_DISABLE_AUTOUPDATE

Disable automatic updates

OPENCODE_DISABLE_PRUNE

Disable session pruning

OPENCODE_DISABLE_TERMINAL_TITLE

Disable terminal title changes

OPENCODE_DISABLE_DEFAULT_PLUGINS

Disable built-in plugins

OPENCODE_DISABLE_LSP_DOWNLOAD

Disable automatic LSP server downloads

OPENCODE_DISABLE_AUTOCOMPACT

Disable automatic context compaction

OPENCODE_DISABLE_MODELS_FETCH

Disable fetching model registry

OPENCODE_DISABLE_FILETIME_CHECK

Disable file modification time checking

Claude Code Compatibility

Variable Purpose

OPENCODE_DISABLE_CLAUDE_CODE

Disable reading from .claude directories entirely

OPENCODE_DISABLE_CLAUDE_CODE_PROMPT

Disable reading ~/.claude/CLAUDE.md global instructions

OPENCODE_DISABLE_CLAUDE_CODE_SKILLS

Disable loading .claude/skills/ directories

Experimental Features

Variable Purpose

OPENCODE_EXPERIMENTAL

Enable ALL experimental features at once

OPENCODE_EXPERIMENTAL_LSP_TOOL

Enable LSP tool (goToDefinition, findReferences, etc.)

OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS

Override default bash timeout (default: 120000ms)

OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX

Override maximum output tokens

OPENCODE_EXPERIMENTAL_FILEWATCHER

Enable experimental file watcher

OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER

Disable file watcher

OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT

Disable copy-on-select behavior

OPENCODE_EXPERIMENTAL_ICON_DISCOVERY

Enable icon discovery

OPENCODE_EXPERIMENTAL_OXFMT

Enable oxfmt formatter

OPENCODE_EXPERIMENTAL_EXA

Enable Exa web search (alternative to OPENCODE_ENABLE_EXA)

OPENCODE_EXPERIMENTAL_LSP_TY

Enable ty LSP server

OPENCODE_EXPERIMENTAL_MARKDOWN

Enable experimental markdown rendering

OPENCODE_EXPERIMENTAL_PLAN_MODE

Enable experimental plan mode features

Recommended .zshenv Configuration

# Provider API keys (use gopass or age-encrypted source in practice)
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
export DEEPSEEK_API_KEY="..."
export GOOGLE_GENERATIVE_AI_API_KEY="..."

# OpenCode feature flags
export OPENCODE_ENABLE_EXA=1                      # Enable web search
export OPENCODE_EXPERIMENTAL_LSP_TOOL=true         # Enable LSP tool
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=300000  # 5min bash timeout

# Disable Claude Code compat if not needed
# export OPENCODE_DISABLE_CLAUDE_CODE=1

Session Sharing & History

Session Sharing

OpenCode can share sessions as viewable links. Three sharing modes:

{
  "share": {
    "provider": "opencode",
    "mode": "manual"
  }
}
Mode Behavior

"manual" (default)

Share only when explicitly requested via /share or keybind

"auto"

Automatically share all sessions

"disabled"

Disable sharing entirely

Share Commands

Action Method

Share current session

/share command or <leader>s keybind (if configured)

Unshare session

Via keybind (session_unshare)

Export as JSON

opencode export [sessionID]

Import from file/URL

opencode import <file>

Session History

Sessions persist in a local SQLite database. Navigate sessions with:

Keybind Action

<leader>l

Session list (browse all sessions)

<leader>g

Session timeline view

<leader>n

New session

session_fork

Fork current session (branch point)

session_rename

Rename current session

Session Statistics

# View token usage and cost breakdown
opencode stats

Shows per-provider token usage, cost estimates, and session counts.

Snapshot System (Undo/Redo)

{
  "snapshot": true
}

When enabled (default), OpenCode tracks every file modification:

  • edit, write, apply_patch, multiedit all create snapshots

  • /undo reverts the last file change

  • /redo re-applies the last undone change

  • Keybinds: <leader>u (undo), <leader>r (redo)

  • Snapshots are session-scoped

Auto-Compaction

{
  "compaction": {
    "enabled": true
  }
}

When context approaches token limits, OpenCode automatically summarizes earlier conversation to free space. Disable with:

export OPENCODE_DISABLE_AUTOCOMPACT=1

Or trigger manually with <leader>c keybind.

The experimental.session.compacting plugin hook allows customizing what context is preserved during compaction.

Migration from Claude Code

A systematic mapping of every Claude Code feature to its OpenCode equivalent. This is not about replacing — it is about translating a battle-tested configuration into a provider-agnostic system.

Configuration File Mapping

Claude Code OpenCode Notes

~/.claude/CLAUDE.md

AGENTS.md + instructions config

AGENTS.md is per-repo. Global rules go in ~/.config/opencode/ instruction files.

~/.claude/settings.json

~/.config/opencode/opencode.json

Provider config, permissions, MCP, agents.

~/.claude/keybindings.json

~/.config/opencode/tui.json

Keybindings + theme + scroll + diff config.

.claude/CLAUDE.md

.opencode/ + AGENTS.md

Project instructions in AGENTS.md. Agents/commands/modes in .opencode/.

.claude/settings.local.json

<repo>/opencode.json

Project config merges with global.

.claude/agents/*.md

.opencode/agents/*.md

Same concept, slightly different frontmatter schema.

.claude/skills/*/SKILL.md

.opencode/skills/*/SKILL.md

Cross-compatible! OpenCode reads .claude/skills/ directories natively.

.claude/rules/*.md

.opencode/modes/*.md + AGENTS.md

Rules become modes or instruction files. No auto-load by file type.

~/.claude/output-styles/*.md

AGENTS.md instructions

No dedicated output style system. Embed tone directives in AGENTS.md.

~/.claude/hooks/*.sh

.opencode/plugins/*.ts

Bash hooks become JS/TS plugins. Richer event model.

Feature Parity Checklist

Feature Claude Code OpenCode Migration Action

Global instructions

CLAUDE.md (873 lines)

AGENTS.md + instructions

Split into AGENTS.md (project) + global instruction files

Permissions (107 allow)

settings.json

opencode.json permission

Translate Bash(command:*) to bash(command *) format

Permissions (10 deny)

settings.json

opencode.json permission.deny

Direct translation

Auto-backup on edit

PreToolUse hook

Plugin or snapshot system

Use built-in snapshots; optionally add backup plugin

AsciiDoc attribute validation

PostToolUse hook

Plugin

Port validate-asciidoc-attrs.sh to TS plugin

ShellCheck on save

PostToolUse hook

Plugin

Port shell validation to TS plugin

Sensitive file warning

UserPromptSubmit hook

Plugin

Port staging check to TS plugin

Session banner

SessionStart hook

Plugin (onSessionStart)

Display environment info on startup

/deploy skill

.claude/skills/deploy/

.opencode/skills/deploy/ (or same path)

Zero migration — OpenCode reads .claude/skills/

/worklog skill

.claude/skills/worklog/

.opencode/skills/worklog/ (or same path)

Zero migration — cross-compatible

/session skill

.claude/skills/session/

.opencode/skills/session/ (or same path)

Zero migration — cross-compatible

doc-auditor agent

.claude/agents/doc-auditor.md

.opencode/agents/doc-auditor.md

Translate frontmatter (tools → permission, model format)

build-fixer agent

.claude/agents/build-fixer.md

.opencode/agents/build-fixer.md

Translate frontmatter

AsciiDoc rule (auto-load)

.claude/rules/asciidoc.md

AGENTS.md or mode

No auto-load equivalent. Embed in AGENTS.md or create review mode.

Output style (professional)

output-styles/professional.md

AGENTS.md tone section

Embed communication rules in AGENTS.md

Undo/redo

Not available

Built-in (/undo, /redo)

New capability — no migration needed

Theme

Not available

tui.json + custom themes

New capability — Catppuccin Mocha

Desktop app

Not available

Beta (Linux AppImage/DEB/RPM)

New capability

Migration Priority Order

  1. Install OpenCode and verify basic operation

  2. Configure providers — Ollama, DeepSeek, Copilot, OpenAI, Gemini, Claude

  3. Set up AGENTS.md — Port core CLAUDE.md rules

  4. Verify skills — Existing .claude/skills/ should work immediately

  5. Translate agents — Port agent frontmatter to OpenCode format

  6. Build plugins — Port bash hooks to TS plugins

  7. Configure permissions — Translate allow/deny lists

  8. Set up theme — Catppuccin Mocha

  9. Customize keybindings — Match muscle memory from Claude Code

  10. Test workflows — Run daily operations cycle end-to-end

What You Lose

Be honest about what is not yet available:

  • Path-specific rule auto-loading — Claude Code auto-loads rules for .adoc, .sh, etc. OpenCode requires modes or AGENTS.md.

  • Hook simplicity — Bash hooks are simpler to write than TS plugins for quick one-off validations.

  • Anthropic-optimized tooling — Claude Code is specifically tuned for Claude models. OpenCode is provider-agnostic, which means less optimization per provider.

  • Proven maturity — Claude Code backed by Anthropic with focused development. OpenCode is MIT/community.

What You Gain

  • Provider freedom — Six providers, local + cloud, switch mid-session

  • Cost control — Ollama for free local, cheap providers for routine work

  • Undo/redo — Built-in file change rollback

  • Richer customization — Themes, full keybinding control, JS/TS plugins

  • Open source — Inspect, modify, contribute

  • Desktop app — Native GUI option

  • Client/server — Remote control capability

Success Metrics

Configuration Targets

Capability Target Current

Providers configured

6

0 (planning phase)

Custom agents

6+

0 (planned: adoc-linter, build-fixer, worklog-creator, carryover-updater, commit-reviewer, cli-drill-master)

Skills migrated

3 (from Claude Code)

0 (cross-compatible, untested)

Plugins built

4+ (asciidoc-validator, auto-backup, security-guard, shellcheck)

0 (planned)

Custom commands

5+

0 (planned)

Custom modes

2+ (Review, Secure)

0 (planned)

Theme

Catppuccin Domus

0 (built-in Catppuccin available)

AGENTS.md

Fully ported from CLAUDE.md

0 (not started)

Cost Targets

Metric Before (Claude Code) Target (OpenCode)

Monthly API spend

~$50-100 (Anthropic only)

~$20-40 (mixed providers + local)

Local model usage

0% (not supported)

60-70% of all interactions

Cloud API usage

100%

30-40% (complex tasks only)

Free tier usage

0%

Ollama local + Gemini free tier

Workflow Acceleration Targets

Metric Claude Code Baseline OpenCode Target

Worklog creation

<10 seconds (skill)

<10 seconds (same skill, cross-compatible)

Deploy cycle

1 command (/deploy)

1 command (same skill)

Model switch

N/A (single provider)

<2 seconds (Tab or Ctrl+X → M)

Undo mistake

Manual git revert

/undo (instant)

Provider failover

Not possible

Switch provider mid-session if one is down

Parity Checklist

Track progress toward feature parity with the Claude Code configuration:

Feature Parity Notes

Global instructions (CLAUDE.md → AGENTS.md)

[ ]

Port 873 lines to AGENTS.md + instruction files

Permission allow list (107 entries)

[ ]

Translate Bash(command:*) format

Permission deny list (10 entries)

[ ]

Direct translation

Skills (3 implemented)

[~]

Cross-compatible, needs testing

Agents (10 total)

[ ]

Translate frontmatter format

Hooks → Plugins (7 hooks)

[ ]

Port bash to TS

Rules → Modes/Instructions (5 rules)

[ ]

Embed in AGENTS.md or create modes

Output style (professional)

[ ]

Embed in AGENTS.md

Keybindings

[ ]

Map muscle memory to tui.json

Theme (Catppuccin)

[~]

Built-in available, custom variant planned