| --- |
| title: TUI |
| description: Using the OpenCode terminal user interface. |
| --- |
| |
| import { Tabs, TabItem } from "@astrojs/starlight/components" |
|
|
| OpenCode provides an interactive terminal interface or TUI for working on your projects with an LLM. |
|
|
| Running OpenCode starts the TUI for the current directory. |
|
|
| ```bash |
| opencode |
| ``` |
|
|
| Or you can start it for a specific working directory. |
|
|
| ```bash |
| opencode /path/to/project |
| ``` |
|
|
| Once you're in the TUI, you can prompt it with a message. |
|
|
| ```text |
| Give me a quick summary of the codebase. |
| ``` |
|
|
| --- |
| |
| |
|
|
| You can reference files in your messages using `@`. This does a fuzzy file search in the current working directory. |
|
|
| :::tip |
| You can also use `@` to reference files in your messages. |
| ::: |
|
|
| ```text "@packages/functions/src/api/index.ts" |
| How is auth handled in @packages/functions/src/api/index.ts? |
| ``` |
|
|
| The content of the file is added to the conversation automatically. |
|
|
| Configured [references](/docs/references) also appear in `@` autocomplete. Type `@alias` to add the reference root as context, or type `@alias/` to autocomplete files inside that reference. |
|
|
| ```text "@docs/README.md" |
| Compare our setup with @docs/README.md |
| ``` |
|
|
| --- |
| |
| |
|
|
| Start a message with `!` to run a shell command. |
|
|
| ```bash frame="none" |
| !ls -la |
| ``` |
|
|
| The output of the command is added to the conversation as a tool result. |
|
|
| --- |
| |
| |
|
|
| When using the OpenCode TUI, you can type `/` followed by a command name to quickly execute actions. For example: |
|
|
| ```bash frame="none" |
| /help |
| ``` |
|
|
| Most commands also have keyboard shortcuts using `ctrl+x` as the default leader key. [Learn more](/docs/keybinds). |
|
|
| Here are all available slash commands: |
|
|
| --- |
| |
| |
|
|
| Add a provider to OpenCode. Allows you to select from available providers and add their API keys. |
|
|
| ```bash frame="none" |
| /connect |
| ``` |
|
|
| --- |
| |
| |
|
|
| Compact the current session. _Alias_: `/summarize` |
|
|
| ```bash frame="none" |
| /compact |
| ``` |
|
|
| **Keybind:** `ctrl+x c` |
|
|
| --- |
| |
| |
|
|
| Toggle tool execution details. |
|
|
| ```bash frame="none" |
| /details |
| ``` |
|
|
| --- |
| |
| |
|
|
| Open external editor for composing messages. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup). |
|
|
| ```bash frame="none" |
| /editor |
| ``` |
|
|
| **Keybind:** `ctrl+x e` |
|
|
| --- |
| |
| |
|
|
| Exit OpenCode. _Aliases_: `/quit`, `/q` |
|
|
| ```bash frame="none" |
| /exit |
| ``` |
|
|
| **Keybind:** `ctrl+x q` |
|
|
| --- |
| |
| |
|
|
| Export current conversation to Markdown and open in your default editor. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup). |
|
|
| ```bash frame="none" |
| /export |
| ``` |
|
|
| **Keybind:** `ctrl+x x` |
|
|
| --- |
| |
| |
|
|
| Show the help dialog. |
|
|
| ```bash frame="none" |
| /help |
| ``` |
|
|
| --- |
| |
| |
|
|
| Guided setup for creating or updating `AGENTS.md`. [Learn more](/docs/rules). |
|
|
| ```bash frame="none" |
| /init |
| ``` |
|
|
| --- |
| |
| |
|
|
| List available models. |
|
|
| ```bash frame="none" |
| /models |
| ``` |
|
|
| **Keybind:** `ctrl+x m` |
|
|
| --- |
| |
| |
|
|
| Start a new session. _Alias_: `/clear` |
|
|
| ```bash frame="none" |
| /new |
| ``` |
|
|
| **Keybind:** `ctrl+x n` |
|
|
| --- |
| |
| |
|
|
| Redo a previously undone message. Only available after using `/undo`. |
|
|
| :::tip |
| Any file changes will also be restored. |
| ::: |
|
|
| Internally, this uses Git to manage the file changes. So your project **needs to |
| be a Git repository**. |
|
|
| ```bash frame="none" |
| /redo |
| ``` |
|
|
| **Keybind:** `ctrl+x r` |
|
|
| --- |
| |
| |
|
|
| List and switch between sessions. _Aliases_: `/resume`, `/continue` |
|
|
| ```bash frame="none" |
| /sessions |
| ``` |
|
|
| **Keybind:** `ctrl+x l` |
|
|
| --- |
| |
| |
|
|
| Share current session. [Learn more](/docs/share). |
|
|
| ```bash frame="none" |
| /share |
| ``` |
|
|
| --- |
| |
| |
|
|
| List available themes. |
|
|
| ```bash frame="none" |
| /themes |
| ``` |
|
|
| **Keybind:** `ctrl+x t` |
|
|
| --- |
| |
| |
|
|
| Toggle the visibility of thinking/reasoning blocks in the conversation. When enabled, you can see the model's reasoning process for models that support extended thinking. |
|
|
| :::note |
| This command only controls whether thinking blocks are **displayed** - it does not enable or disable the model's reasoning capabilities. To toggle actual reasoning capabilities, use `ctrl+t` to cycle through model variants. |
| ::: |
|
|
| ```bash frame="none" |
| /thinking |
| ``` |
|
|
| --- |
| |
| |
|
|
| Undo last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes. |
|
|
| :::tip |
| Any file changes made will also be reverted. |
| ::: |
|
|
| Internally, this uses Git to manage the file changes. So your project **needs to |
| be a Git repository**. |
|
|
| ```bash frame="none" |
| /undo |
| ``` |
|
|
| **Keybind:** `ctrl+x u` |
|
|
| --- |
| |
| |
|
|
| Unshare current session. [Learn more](/docs/share#un-sharing). |
|
|
| ```bash frame="none" |
| /unshare |
| ``` |
|
|
| --- |
| |
| |
|
|
| Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable. |
|
|
| <Tabs> |
| <TabItem label="Linux/macOS"> |
| ```bash |
| |
| export EDITOR=nano |
| export EDITOR=vim |
|
|
| |
| |
| export EDITOR="code --wait" |
| ``` |
|
|
| To make it permanent, add this to your shell profile; |
| `~/.bashrc`, `~/.zshrc`, etc. |
|
|
| </TabItem> |
|
|
| <TabItem label="Windows (CMD)"> |
| ```bash |
| set EDITOR=notepad |
|
|
| |
| |
| set EDITOR=code --wait |
| ``` |
|
|
| To make it permanent, use **System Properties** > **Environment |
| Variables**. |
|
|
| </TabItem> |
|
|
| <TabItem label="Windows (PowerShell)"> |
| ```powershell |
| $env:EDITOR = "notepad" |
|
|
| |
| |
| $env:EDITOR = "code --wait" |
| ``` |
|
|
| To make it permanent, add this to your PowerShell profile. |
|
|
| </TabItem> |
| </Tabs> |
|
|
| Popular editor options include: |
|
|
| - `code` - Visual Studio Code |
| - `cursor` - Cursor |
| - `windsurf` - Windsurf |
| - `nvim` - Neovim editor |
| - `vim` - Vim editor |
| - `nano` - Nano editor |
| - `notepad` - Windows Notepad |
| - `subl` - Sublime Text |
|
|
| :::note |
| Some editors like VS Code need to be started with the `--wait` flag. |
| ::: |
|
|
| Some editors need command-line arguments to run in blocking mode. The `--wait` flag makes the editor process block until closed. |
|
|
| --- |
| |
| |
|
|
| You can customize TUI behavior through `tui.json` (or `tui.jsonc`). |
|
|
| ```json title="tui.json" |
| { |
| "$schema": "https://opencode.ai/tui.json", |
| "theme": "opencode", |
| "leader_timeout": 2000, |
| "keybinds": { |
| "leader": "ctrl+x", |
| "command_list": "ctrl+p" |
| }, |
| "scroll_speed": 3, |
| "scroll_acceleration": { |
| "enabled": false |
| }, |
| "diff_style": "auto", |
| "cursor": { |
| "style": "block", |
| "blinking": true |
| }, |
| "mouse": true, |
| "attention": { |
| "enabled": true, |
| "notifications": true, |
| "sound": true, |
| "volume": 0.4, |
| "sound_pack": "opencode.default", |
| "sounds": { |
| "error": "./sounds/error.mp3" |
| } |
| } |
| } |
| ``` |
|
|
| This is separate from `opencode.json`, which configures server/runtime behavior. |
|
|
| `keybinds` is merged with built-in defaults, so you only need to configure the shortcuts you want to change. |
|
|
| |
|
|
| - `theme` - Sets your UI theme. [Learn more](/docs/themes). |
| - `keybinds` - Customizes keyboard shortcuts. [Learn more](/docs/keybinds). |
| - `leader_timeout` - Controls how long OpenCode waits after the leader key. Defaults to `2000`. |
| - `scroll_acceleration.enabled` - Enable macOS-style scroll acceleration for smooth, natural scrolling. When enabled, scroll speed increases with rapid scrolling gestures and stays precise for slower movements. **This setting takes precedence over `scroll_speed` and overrides it when enabled.** |
| - `scroll_speed` - Controls how fast the TUI scrolls when using scroll commands (minimum: `0.001`, supports decimal values). Defaults to `3`. **Note: This is ignored if `scroll_acceleration.enabled` is set to `true`.** |
| - `diff_style` - Controls diff rendering. `"auto"` adapts to terminal width, `"stacked"` always shows a single-column layout. |
| - `cursor` - Controls the terminal cursor in TUI input fields. `style` defaults to `"block"`, can be `"underline"`, `"line"`, or `"default"`; `blinking` defaults to `true`. When `style` is `"default"`, the terminal default cursor is restored, so `blinking` has no effect. |
| - `mouse` - Enable or disable mouse capture in the TUI (default: `true`). When disabled, the terminal's native mouse selection/scrolling behavior is preserved. |
| - `attention` - Configures TUI desktop notifications and sounds. Disabled by default. |
|
|
| Use `OPENCODE_TUI_CONFIG` to load a custom TUI config path. |
|
|
| |
|
|
| The TUI can request attention for questions, permissions, session errors, and completed sessions. Enable it with `attention.enabled`; built-in events play sounds when triggered, and non-subagent events request desktop notifications only when the terminal is blurred. |
|
|
| - `enabled` - Enable all attention notifications and sounds. Defaults to `false`. |
| - `notifications` - Allow terminal-mediated desktop notifications when attention is enabled. Defaults to `true`. |
| - `sound` - Allow attention sounds when attention is enabled. Defaults to `true`. |
| - `volume` - Default sound volume from `0` to `1`. Defaults to `0.4`. |
| - `sound_pack` - Sound pack ID to use. Defaults to `opencode.default`. |
| - `sounds` - Override sound files for `default`, `question`, `permission`, `error`, `done`, or `subagent_done`. Paths can be absolute, `file://` URLs, or relative to `tui.json`. |
|
|
| --- |
| |
| |
|
|
| You can customize various aspects of the TUI view using the command palette (`ctrl+p`). These settings persist across restarts. |
|
|
| --- |
| |
| |
|
|
| Toggle whether your username appears in chat messages. Access this through: |
|
|
| - Command palette: Search for "username" or "hide username" |
| - The setting persists automatically and will be remembered across TUI sessions |
|
|
