- quickstart.md: 5-minute path from curl to first commit - zen.md: model gateway with full lineup, pricing, BYOK, patterns - tui.md: keybinds, leader chords, themes, customization, sessions - agents.md: custom agents and subagents, full frontmatter, permission map - commands.md: custom slash commands, placeholders, patterns, override rules - skills.md: discoverable workflows, SKILL.md format, description-as-trigger - plugins.md: lifecycle hooks, full event catalog, four real patterns - mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers, with mermaid N×M → N+M diagram - migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does better" subsections so the comparisons aren't one-sided - workflows.md: seven real recipes (TDD, bug investigation, multi-agent review, cross-repo research, migrations, CI, visual iteration) — CI example shows GitHub Actions + GitLab CI to avoid platform bias Every model slug, permission key, config key, env var, and CLI flag verified against the JSON schema or the live docs site.
6.3 KiB
TUI Mastery
The terminal UI is where you'll spend most of your time. This page goes deeper than the README's TUI section.
Layout
┌─────────────────────────────────────────────────────────────┐
│ [agent: build] session: "fix-auth-bug" tokens │ ← top bar
├─────────────────────────────────────────────────────────────┤
│ │
│ Conversation (scrollable) │
│ │
│ │
├─────────────────────────────────────────────────────────────┤
│ > prompt input │ ← input box
└─────────────────────────────────────────────────────────────┘
Use the leader key (default ctrl+x) for session-level actions, and readline shortcuts inside the input box.
Full keybind reference
Leader chords (default leader: ctrl+x)
| Binding | Action |
|---|---|
ctrl+x n |
New session |
ctrl+x l |
List sessions |
ctrl+x g |
Timeline view |
ctrl+x c |
Compact (summarize) session |
ctrl+x e |
Open $EDITOR to compose a long prompt |
ctrl+x m |
Browse models |
ctrl+x t |
Switch theme |
ctrl+x u / ctrl+x r |
Undo / Redo |
ctrl+x b |
Toggle sidebar |
ctrl+x y |
Copy messages |
ctrl+x q |
Quit |
ctrl+p |
Command palette |
Top-level
| Key | Action |
|---|---|
Tab |
Cycle primary agents (build ↔ plan ↔ custom primaries) |
Esc |
Cancel / dismiss |
ctrl+c / ctrl+d |
Exit |
Inside the prompt box (readline / emacs-style)
| Key | Action |
|---|---|
ctrl+a / ctrl+e |
Beginning / end of line |
ctrl+k |
Delete to end of line |
ctrl+u |
Delete to beginning of line |
ctrl+r |
Rename current session |
ctrl+d |
Delete current session (when prompt is empty) |
Prompt prefixes
@<path> — attach files
Fuzzy-search the project and attach matched file content to the prompt. Multiple @s work in one message.
review @src/api/auth.ts and @src/api/auth.test.ts for missing edge cases
!<command> — run shell, attach output
!git diff main...HEAD
based on this diff, write a PR description
The command runs in the project's working directory.
use <mcp-server> — invoke an MCP tool
use playwright open https://example.com and take a screenshot
Slash commands (built-in)
Reference table — full list also lives in reference/slash-commands.md.
| Command | Purpose |
|---|---|
/init |
Generate or update AGENTS.md |
/help |
Show help dialog |
/new (alias /clear) |
New session |
/sessions (aliases /resume, /continue) |
List & switch sessions |
/models |
Browse models |
/connect |
Add a provider |
/themes |
Switch theme |
/compact (alias /summarize) |
Compact session |
/share · /unshare |
Public link control |
/export |
Export to markdown |
/undo · /redo |
Walk edit history |
/editor |
Open $EDITOR |
/details |
Toggle tool execution detail visibility |
/thinking |
Toggle thinking/reasoning blocks |
/exit (aliases /quit, /q) |
Exit |
Customizing keybinds
Drop a tui.json next to your opencode.json:
{
"$schema": "https://opencode.ai/tui.json",
"theme": "tokyonight",
"leader_timeout": 2000,
"scroll_speed": 3,
"keybinds": {
"command_list": "ctrl+p",
"messages_copy": ["<leader>y", "ctrl+shift+c"],
"input_paste": { "key": "ctrl+v", "preventDefault": false }
},
"attention": {
"enabled": true,
"notifications": true,
"sound": true,
"volume": 0.4
}
}
Set a binding to "none" or false to disable. Arrays bind multiple shortcuts to the same action.
Themes
Set the theme in tui.json or with /themes interactively.
Built-in themes:
system · tokyonight · everforest · ayu · catppuccin · catppuccin-macchiato · gruvbox · kanagawa · nord · matrix · one-dark
Custom themes:
- Project:
.opencode/themes/<name>.json - Global:
~/.config/opencode/themes/<name>.json
A custom theme is a JSON file mapping color slots to hex ("#1a1b26"), ANSI numbers (0–255), or "none" (terminal default). Truecolor terminals required.
Sessions
Sessions are conversation snapshots. They persist across restarts and can be:
- listed —
/sessionsorctrl+x l - resumed — pick from the list, or
opencode --continueon the CLI - shared —
/shareproduces a publicopncd.ai/s/<id>URL - exported —
/exportwrites Markdown;opencode export <id>writes JSON - compacted —
/compactsummarizes the conversation to free up context window
💡 Pro tip: Use
/compactaggressively for long-running sessions. The summary preserves intent while dropping verbose tool output that's no longer needed.
Image and file attachment
You can drag files (including images, for multimodal models) into the TUI. Image limits live under attachment.image in opencode.json:
{
"attachment": {
"image": {
"auto_resize": true,
"max_width": 2048,
"max_height": 2048,
"max_base64_bytes": 5242880
}
}
}
Performance & long sessions
| Symptom | Fix |
|---|---|
| TUI feels sluggish on a large repo | Add ignore patterns under watcher.ignore in config |
| Context window filling fast | /compact or pick a model with a bigger context |
| Tools spamming output | /details to hide tool execution chrome |
| Costs rising | opencode stats --days 7 --models to find the offender |
📚 Full TUI reference: opencode.ai/docs/tui · keybinds at opencode.ai/docs/keybinds.