mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
- Bump every version pin, pricing table, and model ID to the verified 2026-07-05 state (v1.17.13): Claude Fable 5 / Sonnet 5 on Zen, new free tier, deprecation sunset table, v1.17.x changelog section - Cover gaps: OpenCode Go vs Zen billing, Anthropic subscription-login removal (PR #18186), MCP resources, --mini mode, --auto flag, yolo mode - Fix correctness bugs: command-template !`cmd` syntax in docs and .opencode/commands, protect-secrets regex missing 'cat .env', dual plugin exports, quickstart PATH fix, Playwright MCP flags, ctrl+d keybind conflict, agent/command required-field claims - Fix links: cursor.com, windsurf.com, platform.claude.com, code.claude.com, opencode.ai/discord, Vercel Grep announcement - Rebrand: banner (Images/banner.svg), 1280x640 social preview asset, hero redesign with star CTA, ecosystem stats, private vulnerability reporting channel, CI-matching local checks, MD060 lint opt-out
197 lines
7.0 KiB
Markdown
197 lines
7.0 KiB
Markdown
# 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) |
|
||
| `shift+tab` | Cycle primary agents in reverse |
|
||
| `Esc` | Cancel / dismiss |
|
||
| `ctrl+c` / `ctrl+x q` | Exit |
|
||
|
||
> 🆕 v1.17.12 added **yolo mode** — auto-approve permission prompts from within the TUI. See the [permissions reference](reference/permissions.md) before turning it on.
|
||
|
||
### 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.
|
||
|
||
```text
|
||
review @src/api/auth.ts and @src/api/auth.test.ts for missing edge cases
|
||
```
|
||
|
||
### `!<command>` — run shell, attach output
|
||
|
||
```text
|
||
!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
|
||
|
||
```text
|
||
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`](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`:
|
||
|
||
```json
|
||
{
|
||
"$schema": "https://opencode.ai/tui.json",
|
||
"theme": "tokyonight",
|
||
"leader_timeout": 2000,
|
||
"scroll_speed": 3,
|
||
"diff_style": "auto",
|
||
"mouse": true,
|
||
"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.
|
||
|
||
Other top-level keys worth knowing: `diff_style` (`"auto"` adapts to terminal width, `"stacked"` forces single-column diffs), `mouse` (capture toggle, default `true`), and `scroll_acceleration` (macOS-style smooth scroll that overrides `scroll_speed`). The `attention` block also takes `sound_pack` (default `"opencode.default"`) and a `sounds` map for per-event overrides (`default`, `question`, `permission`, `error`, `done`, `subagent_done`).
|
||
|
||
## 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** — `/sessions` or `ctrl+x l`
|
||
- **resumed** — pick from the list, or `opencode --continue` on the CLI
|
||
- **shared** — `/share` produces a public `opncd.ai/s/<id>` URL
|
||
- **exported** — `/export` writes Markdown; `opencode export <id>` writes JSON
|
||
- **compacted** — `/compact` summarizes the conversation to free up context window
|
||
|
||
> 💡 **Pro tip:** Use `/compact` aggressively 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`:
|
||
|
||
```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](https://opencode.ai/docs/tui) · keybinds at [opencode.ai/docs/keybinds](https://opencode.ai/docs/keybinds).
|
||
|
||
---
|
||
|
||
*Last reviewed: 2026-07-05.*
|