Skip to content
Learn Compare Recipes Ecosystem Source Code Docs

TUI

OpenCode provides an interactive terminal interface (TUI) for working on your projects with an LLM.

Start OpenCode for the current directory:

opencode

Or for a specific directory:

opencode /path/to/project

File References

You can reference files in your messages using @. This does a fuzzy file search:

How is auth handled in @packages/functions/src/api/index.ts?

The file content is added to the conversation automatically.

Configured references also appear in @ autocomplete.

Type @alias to add a configured reference root as context, or @alias/ to autocomplete files inside it. See References for details.

Bash Commands

Start a message with ! to run a shell command:

!ls -la

The command output is added to the conversation.

Commands

Type / followed by a command name to execute actions:

/help

Most commands have keyboard shortcuts using ctrl+x as the default leader key.

Connect

Add a provider to OpenCode:

/connect

Compact

Compact the current session. Alias: /summarize

Keybind: ctrl+x c

Details

Toggle tool execution details:

/details

Editor

Open external editor for composing messages. Uses EDITOR environment variable.

Keybind: ctrl+x e

Exit

Exit OpenCode. Aliases: /quit, /q

Keybind: ctrl+x q

Export

Export current conversation to Markdown and open in editor.

Keybind: ctrl+x x

Help

Show the help dialog:

/help

Init

Guided setup for creating or updating AGENTS.md.

Models

List available models.

Keybind: ctrl+x m

New

Start a new session. Alias: /clear

Keybind: ctrl+x n

Redo

Redo a previously undone message. Only available after /undo.

Note: File changes are also restored. Internally uses Git, so the project must be a Git repository.

Keybind: ctrl+x r

Sessions

List and switch between sessions. Aliases: /resume, /continue

Keybind: ctrl+x l

Share

Share current session for collaboration.

Themes

List available themes.

Keybind: ctrl+x t

Thinking

Toggle visibility of thinking/reasoning blocks. When enabled, you can see the model’s reasoning process.

Note: This only controls display, not actual reasoning capabilities. Use ctrl+t to toggle reasoning.

Undo

Undo last message. Removes the most recent user message, all subsequent responses, and any file changes.

Note: Internally uses Git to manage file changes. Project must be a Git repository.

Keybind: ctrl+x u

Unshare

Unshare current session.

Editor Setup

Both /editor and /export use the editor in your EDITOR environment variable.

Linux/macOS:

export EDITOR=nano  # or vim
export EDITOR="code --wait"  # for VS Code

Windows (CMD):

set EDITOR=notepad
set EDITOR=code --wait

Windows (PowerShell):

$env:EDITOR = "code --wait"

To make the setting permanent, add it to your shell profile (~/.bashrc, ~/.zshrc) on Linux/macOS, to your PowerShell profile on Windows PowerShell, or use System Properties > Environment Variables on Windows CMD.

Popular editor options include code (VS Code), cursor (Cursor), windsurf (Windsurf), nvim (Neovim), vim, nano, notepad (Windows Notepad), and subl (Sublime Text).

Configure

Customize TUI behavior through tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

tui.json is separate from opencode.json, which configures server/runtime behavior. Its keybinds entries merge with built-in defaults, so you only need to set the shortcuts you want to change.

Options

  • theme - Sets your UI theme
  • keybinds - Customizes keyboard shortcuts
  • leader_timeout - Wait time after leader key (default: 2000)
  • scroll_speed - Controls scrolling speed (default: 3)
  • diff_style - Diff rendering: "auto" or "stacked"
  • mouse - Enable/disable mouse capture (default: true)
  • attention - Desktop notifications and sounds
  • cursor - Terminal cursor in input fields: style defaults to "block" (can be "underline", "line", or "default"), blinking defaults to true ("default" restores the terminal cursor and ignores blinking)
  • scroll_acceleration.enabled - macOS-style scroll acceleration; takes precedence over and overrides scroll_speed when enabled

Use OPENCODE_TUI_CONFIG to load a custom TUI config path. Note that scroll_speed supports decimal values down to 0.001 and is ignored when scroll_acceleration.enabled is true.

Attention

Configure TUI notifications and sounds:

  • enabled - Enable all attention features (default: false)
  • notifications - Desktop notifications (default: true)
  • sound - Attention sounds (default: true)
  • volume - Sound volume 0-1 (default: 0.4)
  • sound_pack - Sound pack ID (default: 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

Attention triggers for questions, permissions, session errors, and completed sessions. Non-subagent events request desktop notifications only when the terminal is blurred.

Customization

You can customize TUI view through the command palette (ctrl+p):

  • Username display - Toggle whether your username appears in chat messages