Skip to content
BranchesTags

Repository files navigation

OpenCode Cheat Sheet (Beta)

OpenCode cheat sheet

Your practical guide to using OpenCode effectively — from first run to advanced agentic workflows.

A reference for developers who want to leverage OpenCode's agentic capabilities while staying in control. Focuses on patterns that augment your thinking, not replace it.

Note: This is a Beta sheet. OpenCode moves fast — we're still aligning every command and example against the live CLI and docs. If something is off (or you quietly notice it isn't), tell us. Until then, treat this as a living draft and verify the surprising bits against the official OpenCode documentation.

Based on official OpenCode documentation — Commands verified against the OpenCode docs and opencode --help (v1.18.3). For the most up-to-date information, always refer to the official docs.

Quick Start

# Install with the official install script (recommended)
curl -fsSL https://opencode.ai/install | bash

# Or with Node.js
npm install -g opencode-ai

# Or with Bun
bun install -g opencode-ai

# Or with pnpm
pnpm install -g opencode-ai

# Or with Homebrew (most up to date: the OpenCode tap)
brew install anomalyco/tap/opencode

# Launch OpenCode in the current project
cd /path/to/project
opencode

# Check version
opencode --version

Table of Contents

Level 1: Getting Started

Essential commands to start using OpenCode effectively.

Installation & Setup 
# Install with the official script
curl -fsSL https://opencode.ai/install | bash

# Or with a package manager
npm install -g opencode-ai
bun install -g opencode-ai
pnpm install -g opencode-ai

# Homebrew (macOS / Linux) — the OpenCode tap is most current
brew install anomalyco/tap/opencode

# Verify installation
opencode --version

On Windows, OpenCode recommends WSL. Native options also exist:

# Chocolatey
choco install opencode

# Scoop
scoop install opencode

# npm
npm install -g opencode-ai
First Steps & Authentication 
# Start the TUI in the current directory
opencode

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

# Authenticate a provider (stores keys in ~/.local/share/opencode/auth.json)
opencode auth login

# List authenticated providers
opencode auth ls

# Log out of a provider
opencode auth logout

In the TUI, /connect opens the same provider setup flow and points you to opencode.ai/auth for API keys. You can also sign in with GitHub (Copilot) or OpenAI (ChatGPT Plus/Pro) directly.

Initialize a Project 
# Inside the TUI, analyze the project and create an AGENTS.md
/init

/init generates an AGENTS.md in the project root with structure and coding patterns. Commit it to Git so OpenCode (and teammates) get project context on every run.

Basic Navigation 
# Keyboard shortcuts in the TUI (leader key: ctrl+x)
ctrl+x n                  # New session (alias: /clear)
ctrl+x l                  # List/switch sessions (alias: /sessions, /resume, /continue)
ctrl+x u                  # Undo last message + file changes (needs Git repo)
ctrl+x r                  # Redo an undone message
ctrl+x c                  # Compact / summarize session (alias: /compact)
ctrl+x e                  # Open external editor (alias: /editor)
ctrl+x x                  # Export conversation to Markdown (alias: /export)
ctrl+x q                  # Exit (alias: /exit, /quit, /q)
ctrl+x m                  # List models (alias: /models)
ctrl+x t                  # List themes (alias: /themes)

# Message prefixes
@path/to/file.ts         # Fuzzy file reference (adds file contents to context)
!ls -la                  # Run a shell command inline

Level 2: Basic Commands

Core patterns for everyday development.

Slash Commands — Essentials

Use these inside an active OpenCode session (type / to see the popup).

/connect                  # Add a provider and paste API keys
/compact                  # Compact session context (alias: /summarize)
/details                  # Toggle tool execution details
/editor                   # Compose message in $EDITOR
/exit                     # Quit OpenCode (aliases: /quit, /q)
/export                   # Export conversation to Markdown
/help                     # Show help dialog
/init                     # Create or update AGENTS.md
/models                   # List available models
/new                      # Start a new session (alias: /clear)
/redo                     # Redo an undone message
/sessions                 # List and switch sessions (aliases: /resume, /continue)
/share                    # Share current session (creates a link)
/themes                   # List available themes
/thinking                 # Toggle visibility of thinking/reasoning blocks
/undo                     # Undo last message and its file changes
/unshare                  # Unshare current session
Agents: Build vs Plan

OpenCode ships two built-in primary agents you cycle between with the Tab key:

  • Build — the default agent, all tools enabled. Use for real implementation work.
  • Plan — read-only planning agent. edit and bash default to ask, so it analyzes and proposes without changing your code. Great for "how should I approach this?" before you commit to changes.

Subagents (invoke with @ in a message):

@general     # General-purpose agent; can make file changes, run in parallel
@explore     # Fast, read-only codebase exploration
@scout       # Read-only external docs / dependency research

When to use each:

  • Build: Default for implementation — full file + shell access.
  • Plan: Analyze, propose, review — no unintended changes.
  • Explore/Scout: Dig into a codebase or upstream docs without touching files.
File and Directory Operations 
# Reference files with @ (fuzzy search in the working directory)
"How is auth handled in @packages/functions/src/api/index.ts?"

# Reference a configured reference root
"Compare our setup with @docs/README.md"

# OpenCode reads, writes, and edits files as part of normal work
"Add error handling to src/utils.py"
"Create a new file called components/Button.tsx"
Working with Code 
# Explain and analyze
"Explain what this code does"
"Review this function for bugs"

# Generate and refactor
"Write a function to parse JSON safely"
"Refactor this module to use async/await"

# Use Plan mode first for non-trivial changes
# Press Tab -> describe the feature -> review the plan -> Tab -> "go ahead"
Session Management 
# In the TUI
/new                       # Start a fresh session
/sessions                  # List + switch (alias: /resume, /continue)

# From the CLI
opencode session list                 # List all sessions
opencode session list -n 10           # Last 10 sessions
opencode session delete <sessionID>   # Delete a session

# Continue the last session
opencode -c
opencode --continue

# Resume a specific session
opencode -s <sessionID>
opencode --session <sessionID>

# Fork a session (keeps the original intact)
opencode -c --fork

Sessions persist context — use them for multi-turn problem solving. --fork copies the session so you can explore a different direction safely.

Useful CLI Flags 
# Model selection (provider/model format)
opencode -m anthropic/claude-sonnet-4-5 "your prompt"
opencode run -m opencode/gpt-5.1-codex "explain this"

# Continue / resume
opencode -c                              # Continue last session
opencode -s <sessionID> --fork           # Resume + fork

# Agent and prompt
opencode --agent plan "draft a migration plan"
opencode --prompt "summarize this repo"

# Auto-approve (dangerous — skips permission prompts for non-denied actions)
opencode run --auto "refactor src/"

# Attach to a running server (avoids MCP cold boots)
opencode run --attach http://localhost:4096 "explain async/await"

Level 3: Intermediate Usage

Configuration and customization options.

Configuration

OpenCode uses a JSON or JSONC config (opencode.json / opencode.jsonc). It supports both formats and loads from several locations, merged (not replaced):

  1. Remote config (.well-known/opencode) — org defaults
  2. Global config — ~/.config/opencode/opencode.json
  3. Custom config — OPENCODE_CONFIG env var
  4. Project config — opencode.json in the project root (highest standard precedence)
  5. .opencode/ directories — agents, commands, skills, plugins
  6. Inline — OPENCODE_CONFIG_CONTENT env var
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": { "port": 4096 }
}

TUI-specific settings live in a separate tui.json (or tui.jsonc):

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": { "command_list": "ctrl+p" }
}

See Config Reference for the full schema.

Model Selection 
# List every model available across your configured providers
opencode models

# Filter by provider
opencode models anthropic

# Refresh the cached model list from models.dev
opencode models --refresh

# Verbose output includes costs/metadata
opencode models --verbose

Set a default model in config:

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Model IDs use the provider/model-id format. With OpenCode Zen you can use curated entries like opencode/gpt-5.1-codex. Cycle reasoning variants with ctrl+t in the TUI.

AGENTS.md for Project Context 
# Run inside the TUI to generate AGENTS.md
/init

AGENTS.md (and any files referenced via instructions in config) gives OpenCode project-specific context. Commit it to Git.

# Project Guidelines

## Tech Stack
- Node.js with Fastify
- PostgreSQL
- Vitest for testing

## Patterns
- Use dependency injection
- Prefer async functions for I/O
- Follow the existing ESLint rules

You can also point OpenCode at instruction files globally:

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}
Permissions

By default OpenCode allows all operations without prompting. Tighten that in config:

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Permission values: "allow", "ask", "deny". Keys accept glob patterns, so you can scope bash precisely:

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Available permission keys: read, edit, glob, grep, list, bash, task, external_directory, todowrite, webfetch, websearch, lsp, skill, question. See Permissions for details.

Skills

  • What they are: Reusable, on-disk instructions OpenCode discovers automatically. Each skill is a folder with a SKILL.md (YAML frontmatter + body). The agent loads them on demand via the native skill tool.
  • Where skills live: OpenCode searches these locations (project paths walk up to the git worktree; global paths are always loaded):
    • Project: .opencode/skills/<name>/SKILL.md
    • Global: ~/.config/opencode/skills/<name>/SKILL.md
    • Claude-compatible: .claude/skills/<name>/SKILL.md, ~/.claude/skills/<name>/SKILL.md
    • Agent-compatible: .agents/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md
  • File format (YAML frontmatter + body): 
    ---
name: your-skill-name          # required, 1-64 chars, lowercase + hyphens only
description: when/why to use   # required, 1-1024 chars
license: MIT                   # optional
---

# Optional body (loaded on demand)
Add references, workflows, or examples here.
  • Using skills: The agent sees available skills in its skill tool description and loads the full content when needed. Reference them from AGENTS.md or prompts.
  • Permissions per skill: Control access in config with pattern-based rules: 
    {
  "permission": {
    "skill": {
      "*": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
  • Sample skills in this repo: Copy or symlink any of the samples below into .opencode/skills/<name>/SKILL.md, then restart OpenCode:
    • skills/mcp-setup/SKILL.md
    • skills/session-management/SKILL.md
    • skills/plan-mode/SKILL.md
  • Troubleshooting: If a skill doesn't appear — verify SKILL.md is all caps, confirm name + description frontmatter, ensure the name is unique, and check that permissions don't deny it.

See Agent Skills for details.

Level 4: Advanced Features

Powerful features for complex workflows.

MCP Integration

MCP (Model Context Protocol) adds external tools alongside OpenCode's built-ins.

# Add an MCP server (interactive prompt for local/remote)
opencode mcp add

# List servers and connection status
opencode mcp list            # or: opencode mcp ls

# Authenticate an OAuth-enabled server
opencode mcp auth <name>
opencode mcp auth list      # auth status for all OAuth-capable servers

# Remove stored OAuth credentials
opencode mcp logout <name>

# Debug OAuth / connectivity for a server
opencode mcp debug <name>

Configure servers in opencode.json (local example):

{
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

Remote example (with auth headers):

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }
    }
  }
}

OAuth-enabled remote servers need no special config — OpenCode detects the 401 and runs the flow automatically. Disable a server with "enabled": false.

Tip: MCP servers add to context. Be selective — a server like GitHub MCP can blow past the context limit fast.

See MCP Servers for details.

Agents & Custom Agents

Define specialized agents in opencode.json or as markdown in ~/.config/opencode/agents/ (or .opencode/agents/).

Markdown agent (.opencode/agents/review.md):

---
description: Reviews code for quality and best practices
mode: subagent
permission:
  edit: deny
  bash: deny
---
You are in code review mode. Focus on code quality, potential bugs,
performance, and security. Provide feedback without making changes.

JSON config:

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, maintainability.",
      "permission": { "edit": "deny" }
    }
  },
  "default_agent": "plan"   // optional: change the default primary agent
}

Manage agents from the CLI:

opencode agent list                       # List all available agents
opencode agent create                     # Interactive agent creator
opencode agent create --path .opencode/agents \
  --description "Docs writer" --mode subagent --permissions "read,bash:deny"

Built-in modes: primary (interact directly, cycle with Tab), subagent (invoke via @ or by the model), all. See Agents for details.

Custom Commands

Create repeatable prompts as commands. Place markdown in ~/.config/opencode/commands/ or .opencode/commands/.

.opencode/commands/component.md:

---
description: Create a new component
---
Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

Run it in the TUI:

/component Button

Prompts support shell output (!command``) and file references (@file):

---
description: Review recent changes
---
Recent git commits:
!`git log --oneline -10`
Review these changes and suggest improvements.

See Commands for details.

Non-Interactive & Scripting 
# Run a single prompt and exit
opencode run "Explain how closures work in JavaScript"

# Attach files to the message
opencode run -f src/app.ts "review this file"

# Output raw JSON events (for automation)
opencode run --format json "list the exported functions in main.go"

# Continue / fork / share from a run
opencode run -c "add tests for utils.ts"
opencode run -s <sessionID> --fork "try a different approach"
opencode run --share "draft the API spec"

# Pipe content in
cat error.log | opencode run "find the root cause"
git diff | opencode run "write a commit message"

# Title the session
opencode run --title "Spike: auth refactor" "plan the work"

opencode run is the scripting entry point — pair it with --attach to a running opencode serve to skip MCP cold boots. See CLI for details.

Server, Web & ACP 
# Headless HTTP server (API access, no TUI)
opencode serve --port 4096

# Headless server + web interface (opens browser)
opencode web --port 4096

# Attach a TUI to a running backend (remote access)
opencode attach http://10.20.30.40:4096

# ACP (Agent Client Protocol) server over stdio
opencode acp

# Run the GitHub agent (typically in Actions)
opencode github run
opencode github install     # Sets up the repo GitHub Actions workflow

Set OPENCODE_SERVER_PASSWORD to require HTTP basic auth on serve/web. See Server and ACP.

Sharing & Importing Sessions 
# In the TUI
/share                      # Create a share link (copied to clipboard)
/unshare                    # Remove the share

# From the CLI
opencode run --share "walk through the bug"
opencode export <sessionID> --sanitize   # Redact sensitive data

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

Sharing is off by default — you opt in per session. Configure globally:

{ "share": "manual" }   // "manual" | "auto" | "disabled"

See Share for details.

Level 5: Expert Workflows

Advanced patterns and automation for power users.

Stats & Cost Tracking 
# Token usage and cost across sessions
opencode stats

# Last N days
opencode stats --days 30

# Top models breakdown
opencode stats --models 5

# Filter by project
opencode stats --project /path/to/project

Use this to spot expensive models and trim waste.

Plan-Mode Workflows

For non-trivial changes, separate thinking from doing:

  1. Press Tab to switch to the Plan agent (read-only).
  2. Describe the feature with context and examples.
  3. Review the proposed plan and iterate.
  4. Press Tab back to Build, then: "Sounds good, go ahead."

This keeps OpenCode from editing files until you've signed off — useful for refactors, migrations, and anything you'd want a junior dev to plan first.

Parallel Subagents

Offload independent research with subagents:

@general research the rate-limit behavior of the Stripe SDK
@explore find every place we call the legacy auth module
@scout check how Next.js 15 handles caching vs our current setup

Primary agents can also launch subagents automatically. Control nesting depth:

{ "subagent_depth": 2 }   // 1 = default (one level); 0 = disable subagents

Control which subagents an agent may invoke:

{
  "agent": {
    "orchestrator": {
      "permission": { "task": { "*": "deny", "code-reviewer": "ask" } }
    }
  }
}
Plugins & Ecosystem 
# Install a plugin (updates config automatically)
opencode plugin opencode-helicone-session
opencode plug @my-org/custom-plugin          # alias: plug

# Install globally
opencode plugin -g some-plugin

# Force replace an existing version
opencode plugin -f some-plugin

Plugins live in .opencode/plugins/ or ~/.config/opencode/plugins/, or load from npm via the plugin config key. See Plugins.

Debugging & Troubleshooting 
# Inspect the fully resolved config (incl. managed settings)
opencode debug config

# Other debug tooling
opencode debug

# Database tools
opencode db path            # Print the database path
opencode db <query>         # Run a query (--format json|tsv)

# Uninstall OpenCode
opencode uninstall --keep-config   # keep config files
opencode uninstall --dry-run       # preview what gets removed

When a remote MCP server fails to authenticate, opencode mcp debug <name> shows auth status and tests the OAuth discovery flow. See Troubleshooting.

Upgrading 
# Upgrade to the latest version
opencode upgrade

# Upgrade to a specific version
opencode upgrade v0.1.48

# Disable autoupdate checks
export OPENCODE_DISABLE_AUTOUPDATE=1

To keep autoupdate on but only notify: "autoupdate": "notify" in config (only when not installed via a package manager).

Command Reference

Global CLI Commands

Command Description
opencode Start the TUI in the current directory (or [project])
opencode run [msg] Run a prompt non-interactively
opencode auth Manage provider credentials (login, list/ls, logout)
opencode models [provider] List available models
opencode mcp Manage MCP servers (add, list/ls, auth, logout, debug)
opencode agent Manage agents (create, list)
opencode session Manage sessions (list, delete <id>)
opencode github Manage the GitHub agent (install, run)
opencode serve Start a headless HTTP server
opencode web Start a headless server with web UI
opencode attach [url] Attach a TUI to a running backend
opencode acp Start an ACP server (stdio)
opencode plugin <module> Install a plugin (plug alias)
opencode pr <number> Checkout a GitHub PR branch, then run OpenCode
opencode export [id] Export a session as JSON
opencode import <file|url> Import a session from file or share URL
opencode stats Token usage and cost statistics
opencode db [query] Database tools
opencode debug Debugging and troubleshooting tools
opencode upgrade [target] Upgrade OpenCode
opencode uninstall Uninstall OpenCode

Common Global Flags

Flag Description
-m, --model Model in provider/model format
-c, --continue Continue the last session
-s, --session Session ID to continue
--fork Fork the session when continuing
--prompt Prompt to use
--agent Agent to use
--auto Auto-approve non-denied permissions (dangerous)
--pure Run without external plugins
-v, --version Print version number
-h, --help Show help

TUI Keybinds (leader: ctrl+x)

Keybind Action
ctrl+x n New session (/new, /clear)
ctrl+x l List/switch sessions (/sessions)
ctrl+x u Undo last message (/undo)
ctrl+x r Redo undone message (/redo)
ctrl+x c Compact session (/compact)
ctrl+x e External editor (/editor)
ctrl+x x Export to Markdown (/export)
ctrl+x m List models (/models)
ctrl+x t List themes (/themes)
ctrl+x q Quit (/exit)
Tab Cycle primary agents (Build / Plan)
ctrl+t Cycle model variants (reasoning effort)

Built-in Agents

Agent Mode Use it for
build primary Default — full tool access for implementation
plan primary Read-only analysis and planning
general subagent Multi-step work; can change files; runs in parallel
explore subagent Fast, read-only codebase exploration
scout subagent Read-only external docs / dependency research

Best Practices

Think Critically

OpenCode is an assistant, not a replacement for your judgment:

  • Review changes before accepting — understand what changed and why (use /undo to roll back)
  • Use Plan mode for non-trivial work — get a proposal, then approve
  • Ask with context — reference files with @, give examples, talk to it like a teammate
  • Question assumptions — if something feels off, dig deeper

Stay Secure

  • Never commit API keys — they live in ~/.local/share/opencode/auth.json, not your repo
  • Tighten permissions with "ask"/"deny" for edit and bash in shared/unknown codebases
  • Be selective with MCP servers — they add to context and can exceed limits
  • Use export --sanitize before sharing sessions that contain secrets

Work Effectively

  • Run /init and commit AGENTS.md for project context
  • Create skills for repetitive, domain-specific workflows
  • Use sessions for multi-turn problems; --fork to explore safely
  • Combine OpenCode with traditional tools (git, grep, your editor)
  • Leverage subagents (@general, @explore, @scout) for parallel research

Continuous Learning

  • Run opencode models --refresh when a provider adds new models
  • Use /thinking to see the model's reasoning on hard problems
  • Build your own agents and commands for team patterns
  • Check opencode stats to understand cost and model usage

Additional Resources

Official OpenCode Documentation:

Repository & Community:

Related Tools:

Tip: Always check the official OpenCode documentation for the latest features and updates. This cheat sheet is a quick reference, but the official docs contain the most comprehensive and up-to-date information.

Contributing

Found an issue, or notice something is off? Contributions are welcome — this is a Beta sheet, so corrections matter.

  • Report bugs or inconsistencies
  • Suggest new examples
  • Share your workflows
  • Improve documentation

License

MIT License — Free to use and modify.

Last updated: July 2026 Based on: OpenCode CLI (npm: opencode-ai, v1.18.3)

This is a Beta reference. Commands and examples are verified against opencode --help and the official docs, but OpenCode evolves quickly — flag anything that drifts.

Last synced: 2026-07-19 via workspace manager

About

Ultimate collection of OpenCode tips, tricks, and workflows that you can use to master OpenCode CLI in minutes.

opencode.ai/

Topics

cheatsheetclicommunityopencodetips-and-tricks

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Used by

Contributors