OpenCode cheatsheet

OpenCode is an open-source AI coding agent with a TUI, CLI, and desktop app — supports any LLM provider, fully extensible via config, plugins, and MCP.

#Getting Started

#Basic Usage

# Start TUI for current directory
$ opencode

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

# Run non-interactively (headless)
$ opencode run "Explain how closures work in JS"

# Continue last session
$ opencode run -c "Fix the failing tests"

# Pipe input into opencode
$ cat error.log | opencode run "Explain this error"

Inside the TUI:

/init           # analyze project, create AGENTS.md
@src/api.ts     # fuzzy-reference a file
!ls -la         # run a shell command inline
Tab             # switch agent (Build / Plan / Ask)

#Introduction

Official Docs (opencode.ai)
GitHub (github.com)
Discord (discord.gg)

#Install

#Script (recommended)

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

#Node.js

$ npm install -g opencode-ai

#macOS / Linux

$ brew install anomalyco/tap/opencode

#Windows

choco install opencode      # Chocolatey
scoop install opencode      # Scoop

#Docker

$ docker run -it --rm ghcr.io/anomalyco/opencode

#Key Concepts

Term	Description
TUI	Interactive terminal UI
`opencode run`	Headless / scripting mode
Session	Saved conversation history
AGENTS.md	Project context for the AI
Snapshot	Git-based undo/redo state
Compaction	Auto-summarize full context
Agent	Task-specific AI persona
MCP	External tool integrations

#TUI Slash Commands

#All Commands

Command	Keybind	Description
`/connect`		Add provider API key
`/init`	`<L>i`	Create / update AGENTS.md
`/new`	`<L>n`	New session (alias: `/clear`)
`/sessions`	`<L>l`	List & switch sessions
`/models`	`<L>m`	List available models
`/themes`	`<L>t`	List & change themes
`/compact`	`<L>c`	Compact session context
`/undo`	`<L>u`	Undo last message + edits
`/redo`	`<L>r`	Redo undone message
`/share`	`<L>s`	Share session (get URL)
`/unshare`		Remove shared session
`/export`	`<L>x`	Export to Markdown
`/editor`	`<L>e`	Open `$EDITOR` for input
`/details`	`<L>d`	Toggle tool details
`/thinking`		Toggle reasoning blocks
`/help`	`<L>h`	Show help dialog
`/exit`	`<L>q`	Exit (alias: `/quit`, `/q`)

<L> = leader key (default ctrl+x)

#Input Tips

Syntax	Effect
`@filename`	Fuzzy file reference
`!command`	Run shell command inline
`Tab`	Cycle agent mode
`Shift+Tab`	Reverse cycle agent
`Drag & drop`	Attach image to prompt
`Ctrl+P`	Command palette
`Ctrl+T`	Cycle model variant
`F2`	Cycle recent model
`Escape`	Interrupt running response

#Editor Setup

# For terminal editors
export EDITOR=nvim
export EDITOR=vim

# For GUI editors (need --wait)
export EDITOR="code --wait"
export EDITOR="cursor --wait"
export EDITOR="zed --wait"

Add to ~/.zshrc or ~/.bashrc to persist.

#Keyboard Shortcuts

#Session Controls

Shortcut	Action
`Ctrl+X` `N`	New session
`Ctrl+X` `L`	Sessions list
`Ctrl+X` `C`	Compact session
`Ctrl+X` `U`	Undo last message
`Ctrl+X` `R`	Redo message
`Ctrl+X` `S`	Share session
`Ctrl+X` `X`	Export to Markdown
`Ctrl+X` `E`	Open editor
`Ctrl+X` `M`	Model picker
`Ctrl+X` `A`	Agent picker
`Ctrl+X` `T`	Theme picker
`Ctrl+X` `H`	Help / command palette
`Ctrl+X` `Q`	Exit
`Ctrl+X` `D`	Toggle tool details
`Ctrl+X` `B`	Toggle sidebar
`Ctrl+X` `G`	Session timeline
`Ctrl+X` `Y`	Copy messages
`Escape`	Interrupt response
`Ctrl+P`	Command palette
`Ctrl+T`	Cycle model variant
`F2`	Next recent model
`Shift+F2`	Prev recent model
`Tab`	Cycle agent forward
`Shift+Tab`	Cycle agent backward

Shortcut	Action
`Page Up`	Scroll page up
`Page Down`	Scroll page down
`Ctrl+Alt+Y`	Scroll line up
`Ctrl+Alt+E`	Scroll line down
`Ctrl+Alt+U`	Half page up
`Ctrl+Alt+D`	Half page down
`Ctrl+G` / `Home`	Jump to top
`Ctrl+Alt+G` / `End`	Jump to bottom

#Input Editing

Shortcut	Action
`Ctrl+A`	Start of line
`Ctrl+E`	End of line
`Alt+B`	Word backward
`Alt+F`	Word forward
`Ctrl+K`	Kill to line end
`Ctrl+U`	Kill to line start
`Ctrl+W`	Kill prev word
`Alt+D`	Kill next word
`Ctrl+V`	Paste
`Return`	Submit message
`Shift+Return`	New line in input

#CLI Commands

#All Commands

Command	Description
`opencode`	Start TUI
`opencode [path]`	Start TUI in directory
`opencode run [msg]`	Headless/non-interactive run
`opencode serve`	Headless HTTP API server
`opencode web`	HTTP server + web UI
`opencode attach [url]`	Attach TUI to remote server
`opencode acp`	Start ACP (JSON-RPC) server
`opencode agent create`	Create new agent
`opencode agent list`	List agents
`opencode auth login`	Configure provider API key
`opencode auth list`	List authenticated providers
`opencode auth logout`	Remove provider credentials
`opencode mcp add`	Add MCP server
`opencode mcp list`	List MCP servers
`opencode mcp auth [name]`	Authenticate OAuth MCP server
`opencode mcp logout [name]`	Remove MCP OAuth credentials
`opencode mcp debug <name>`	Debug MCP connection
`opencode models [provider]`	List available models
`opencode models --refresh`	Refresh models cache
`opencode session list`	List all sessions
`opencode stats`	Show token & cost stats
`opencode export [id]`	Export session as JSON
`opencode import <file>`	Import session / share URL
`opencode github install`	Set up GitHub Actions agent
`opencode github run`	Run GitHub agent
`opencode upgrade [ver]`	Upgrade to latest / specific
`opencode uninstall`	Uninstall opencode

#Headless Mode

# Basic print/run
$ opencode run "Summarize this codebase"

# Continue last session
$ opencode run -c "Fix the lint errors"

# Specific session
$ opencode run -s <session-id> "Add tests"

# Fork a session
$ opencode run -s <id> --fork "Try different approach"

# Attach files
$ opencode run -f diagram.png "Implement this"

# JSON output
$ opencode run "List all TODOs" --format json

# Share the session
$ opencode run --share "Refactor auth module"

# Attach to running server
$ opencode serve &
$ opencode run --attach http://localhost:4096 "task"

#Server & Remote

# Headless API server
$ opencode serve --port 4096

# Web UI server
$ opencode web --port 4096 --hostname 0.0.0.0

# Enable mDNS discovery
$ opencode serve --mdns

# Enable basic auth
$ OPENCODE_SERVER_PASSWORD=secret opencode serve

# ACP server (JSON-RPC over stdio)
$ opencode acp --cwd /my/project

# Attach TUI to remote server
$ opencode attach http://10.20.30.40:4096

#CLI Flags

#TUI Flags

Flag	Short	Description
`--continue`	`-c`	Continue last session
`--session`	`-s`	Session ID to use
`--fork`		Fork on continue
`--prompt`		Initial prompt
`--model`	`-m`	Model (`provider/model`)
`--agent`		Agent to use
`--port`		Port to listen on
`--hostname`		Hostname to listen on

#Run Flags

Flag	Short	Description
`--continue`	`-c`	Continue last session
`--session`	`-s`	Session ID to use
`--fork`		Fork on continue
`--model`	`-m`	Model to use
`--agent`		Agent to use
`--file`	`-f`	Attach file(s)
`--format`		`default` or `json`
`--share`		Share the session
`--title`		Set session title
`--attach`		Attach to server URL
`--port`		Local server port

#Global Flags

Flag	Short	Description
`--help`	`-h`	Display help
`--version`	`-v`	Print version
`--print-logs`		Print logs to stderr
`--log-level`		DEBUG/INFO/WARN/ERROR

#Configuration

#opencode.json

Main config at ~/.config/opencode/opencode.json or ./opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "default_agent": "build",
  "autoupdate": true,
  "snapshot": true,
  "share": "manual",
  "instructions": ["AGENTS.md", "docs/*.md"],
  "provider": {
    "anthropic": {
      "options": { "timeout": 600000 }
    }
  },
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  },
  "server": {
    "port": 4096,
    "mdns": true
  },
  "tools": {
    "write": false,
    "bash": false
  },
  "disabled_providers": ["openai"],
  "enabled_providers": ["anthropic"]
}

#tui.json

TUI config at ~/.config/opencode/tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "keybinds": {
    "leader": "ctrl+x",
    "session_compact": "none"
  }
}

#Config Locations

Source	Path	Priority
Remote	`.well-known/opencode`	1 (lowest)
Global	`~/.config/opencode/opencode.json`	2
Custom	`$OPENCODE_CONFIG` path	3
Project	`./opencode.json`	4
`.opencode/`	agents/, commands/, plugins/	5
Inline	`OPENCODE_CONFIG_CONTENT`	6 (highest)

Configs merge — later sources override conflicting keys only.

#Variable Substitution

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    },
    "anthropic": {
      "options": {
        "apiKey": "{file:~/.secrets/anthropic}"
      }
    }
  }
}

#Environment Variables

#Core Variables

Variable	Type	Description
`OPENCODE_CONFIG`	string	Custom config file path
`OPENCODE_TUI_CONFIG`	string	Custom TUI config path
`OPENCODE_CONFIG_DIR`	string	Custom config directory
`OPENCODE_CONFIG_CONTENT`	string	Inline JSON config
`OPENCODE_PERMISSION`	string	Inline JSON permissions
`OPENCODE_AUTO_SHARE`	bool	Auto-share sessions
`OPENCODE_SERVER_PASSWORD`	string	Basic auth for serve/web
`OPENCODE_SERVER_USERNAME`	string	Auth username (default: opencode)
`OPENCODE_MODELS_URL`	string	Custom models config URL
`OPENCODE_ENABLE_EXA`	bool	Enable Exa web search
`OPENCODE_DISABLE_AUTOUPDATE`	bool	Disable update checks
`OPENCODE_DISABLE_PRUNE`	bool	Disable old data pruning
`OPENCODE_DISABLE_AUTOCOMPACT`	bool	Disable auto-compaction
`OPENCODE_DISABLE_LSP_DOWNLOAD`	bool	Disable LSP auto-download
`OPENCODE_DISABLE_MODELS_FETCH`	bool	Disable remote model fetch
`OPENCODE_DISABLE_CLAUDE_CODE`	bool	Disable .claude/ reading
`OPENCODE_GIT_BASH_PATH`	string	Git Bash path (Windows)
`OPENCODE_CLIENT`	string	Client ID (default: cli)

#Experimental Variables

Variable	Description
`OPENCODE_EXPERIMENTAL`	Enable all experimental features
`OPENCODE_EXPERIMENTAL_PLAN_MODE`	Enable plan mode
`OPENCODE_EXPERIMENTAL_LSP_TOOL`	Enable experimental LSP tool
`OPENCODE_EXPERIMENTAL_FILEWATCHER`	Enable full-dir file watcher
`OPENCODE_EXPERIMENTAL_MARKDOWN`	Experimental markdown features
`OPENCODE_EXPERIMENTAL_EXA`	Experimental Exa features
`OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	Max output tokens override
`OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS`	Bash timeout in ms

#Also see

OpenCode Docs (opencode.ai)
CLI Reference (opencode.ai)
TUI Guide (opencode.ai)
Config Reference (opencode.ai)
GitHub Repository (github.com)

OpenCode cheatsheet

#Getting Started

#Basic Usage

#Introduction

#Install

#Script (recommended)

#Node.js

#macOS / Linux

#Windows

#Docker

#Key Concepts

#TUI Slash Commands

#All Commands

#Input Tips

#Editor Setup

#Keyboard Shortcuts

#Session Controls

#Scroll Navigation

#Input Editing

#CLI Commands

#All Commands

#Headless Mode

#Server & Remote

#CLI Flags

#TUI Flags

#Run Flags

#Global Flags

#Configuration

#opencode.json

#tui.json

#Config Locations

#Variable Substitution

#Environment Variables

#Core Variables

#Experimental Variables

#Also see