Terminal UI

The Terminal User Interface (TUI) is opencode's primary interface -- a full-featured, keyboard-driven chat application for interacting with AI coding agents.

Starting the TUI

Launch the TUI from any directory:

opencode

Specify a project directory:

opencode /path/to/your/project

Pass an initial prompt to start a conversation immediately:

opencode "Explain the project structure"

Interface Layout

The TUI is divided into several panels:

┌──────────────────────────────────────────────────────┐
│  Session Header (model, session ID, agent mode)       │
├──────────────────────────────────────────────────────┤
│                                                        │
│  Conversation History                                  │
│  ┌──────────────────────────────────────────────────┐  │
│  │ User: What does this project do?                 │  │
│  │                                                   │  │
│  │ Agent: This project is a web application that...  │  │
│  │                                                   │  │
│  │ [File: src/index.ts]                              │  │
│  │ ```typescript                                     │  │
│  │ const app = createApp();                          │  │
│  │ ```                                               │  │
│  └──────────────────────────────────────────────────┘  │
│                                                        │
│  Input Area (type your message here)                   │
│  [ > @app.ts How does the router work?            ]    │
│                                                        │
│  Status Bar (provider, mode, connection status)        │
├──────────────────────────────────────────────────────┤
│  [Ctrl+P] Palette  [Tab] Mode  [:@] Files  [/?] Cmds │
└──────────────────────────────────────────────────────┘

Messaging

Type your message at the prompt and press Enter to send it.

Multi-line Messages

Use Alt+Enter or Esc+Enter to insert a newline for multi-line prompts.

File References with @

Type @ followed by a filename to trigger a fuzzy file search:

How does the authentication flow work in @auth.

Select the file from the dropdown to include its contents in the conversation context. You can reference multiple files in a single message:

Compare the implementations in @auth.ts and @auth.test.ts

Shell Commands with !

Prefix a message with ! to execute a shell command directly:

!npm test
!git log --oneline -5
!ls -la src/

The command output is captured and displayed in the conversation.

Slash Commands

Prefix a message with / to access built-in commands:

Command	Description
`/connect`	Open the provider connection manager
`/compact`	Summarize and compress the current session history
`/details`	Show detailed session information
`/editor`	Edit the current prompt in the system $EDITOR
`/exit`	Exit opencode
`/export`	Export the session transcript to a file via $EDITOR
`/help`	Display help information
`/init`	Initialize project context (creates AGENTS.md)
`/models`	List and switch between models/providers
`/new`	Start a fresh session
`/redo`	Re-apply the last undone change
`/sessions`	List all saved sessions
`/share`	Share the current session
`/themes`	Browse and select color themes
`/thinking`	Toggle the model's thinking/reasoning display
`/undo`	Revert the last agent modification
`/unshare`	Revoke sharing on the current session

Command Palette

Press Ctrl+P to open the command palette. This is a fuzzy-search interface that lists every available action, command, and setting. Start typing to filter, press Enter to execute.

Available palette entries include:

All slash commands
Theme switching
Config editing
Session navigation
Agent switching
View toggles

Keybinds

Default keyboard shortcuts:

Binding	Action
`Ctrl+P`	Open command palette
`Ctrl+C`	Cancel current request
`Ctrl+D`	Scroll down one page
`Ctrl+U`	Scroll up one page
`Home`	Scroll to top of conversation
`End`	Scroll to bottom of conversation
`PgUp` / `PgDn`	Page up/down
`Up` / `Down`	Navigate message history (when input is empty)

Actions

Binding	Action
`Ctrl+X C`	Compact session
`Ctrl+X E`	Open prompt in editor
`Ctrl+X Q`	Exit
`Ctrl+X X`	Export session
`Ctrl+X M`	Show model list
`Ctrl+X N`	New session
`Ctrl+X R`	Redo
`Ctrl+X U`	Undo
`Ctrl+X L`	List sessions
`Ctrl+X T`	Open theme selector
`Alt+Enter`	Insert newline

Agent Switching

Binding	Action
`Tab`	Cycle between Build and Plan primary agents
`Shift+Tab`	Cycle in reverse

Search

Binding	Action
`Ctrl+F`	Search within the current conversation
`Ctrl+G`	Find next search result

Agent Mode Switching

Press Tab to switch between the Build and Plan primary agents:

Build mode: The agent actively reads/writes files, runs commands, and applies changes. Use this when you want work done.
Plan mode: The agent researches, analyzes, and produces a detailed plan before any code is written. Use this for complex tasks where you want to review the approach first.

The current mode is displayed in the session header. You can also switch agents via the command palette.

Session Management

Child / Parent Sessions

Each conversation creates a parent session. When you send a new message, a child session is created. This creates a tree structure:

Session A (initial)
├── Session B (second message)
│   ├── Session D (fourth message)
│   └── Session E (fifth message)
└── Session C (third message)

Navigate between sessions with /sessions. Select any session to resume it. The tree structure lets you explore different approaches without losing context.

Undo and Redo

opencode creates automatic git snapshots before every file modification:

/undo   # Revert the last modification
/redo   # Reapply a reverted modification

Snapshots are taken per-file before any edit, write, or patch operation. You can undo multiple steps sequentially.

Session Details

/details

Shows the current session's ID, parent session, creation time, active provider and model, and file change count.

Start Fresh

/new

Creates a new session in the same project. Previous sessions remain available via /sessions.

Editor Integration

/editor Command

Running /editor opens your current message in the system's $EDITOR. This is useful for composing long or complex prompts.

Set the EDITOR environment variable:

export EDITOR="code --wait"   # VS Code
export EDITOR="nvim"          # Neovim
export EDITOR="vim"           # Vim
export EDITOR="nano"          # Nano

The --wait flag is important for GUI editors -- it makes the editor block until the file is closed.

/export Command

Running /export opens the full session transcript in $EDITOR for saving. The transcript is written to a temporary file. Save it to your desired location.

Theme System

Browse and apply themes:

/themes

Built-in themes include:

catppuccin-latte, catppuccin-mocha, catppuccin-frappe, catppuccin-macchiato
dracula, dracula-pro
nord, nord-light
one-dark, one-light
tokyo-night, tokyo-night-light
gruvbox, gruvbox-light
solarized-dark, solarized-light
monokai
github-dark, github-light

TUI Configuration

The TUI is configured via tui.json, located at ~/.config/opencode/tui.json. This file controls theme, keybinds, scrolling behavior, mouse support, notifications, and diff display.

Example tui.json

{
  "theme": "catppuccin-mocha",
  "keybinds": [],
  "scroll_speed": 3,
  "scroll_acceleration": true,
  "mouse": true,
  "attention": {
    "notifications": true,
    "sound": "chime"
  },
  "diff_style": "unified",
  "leader_timeout": 1000,
  "showUsername": false
}

Options

Option	Type	Default	Description
`theme`	string	`"catppuccin-latte"`	Theme name or path to custom theme
`keybinds`	array	`[]`	Custom keybinding overrides
`scroll_speed`	number	`3`	Lines per scroll step
`scroll_acceleration`	boolean	`true`	Accelerate scrolling with duration
`mouse`	boolean	`true`	Enable mouse support
`attention.notifications`	boolean	`false`	Desktop notifications on agent actions
`attention.sound`	string / null	`null`	Sound file to play on attention events
`diff_style`	string	`"unified"`	Diff display style (`"unified"` or `"split"`)
`leader_timeout`	number	`1000`	Timeout in ms for leader key sequences (e.g., `Ctrl+X`)
`showUsername`	boolean	`true`	Show username in the UI

Attention Feature

When attention.notifications is enabled, opencode sends desktop notifications when the agent takes an action. This is useful when you're context-switching or waiting for a long-running task.

Configure notification sounds by setting attention.sound to a path to a .wav or .mp3 file:

{
  "attention": {
    "notifications": true,
    "sound": "/path/to/chime.wav"
  }
}

Image Support

If your configured model supports vision (e.g., Claude, GPT-4o, Gemini), you can include images in your prompts:

Drag and drop: Drag an image file from your file manager onto the TUI to attach it
Clipboard: Copy an image and paste it into the input area

Images are displayed inline in the conversation and sent to the model as part of your message.

Customization

Custom Themes

Create a custom theme by defining a JSON file:

{
  "name": "my-theme",
  "type": "dark",
  "colors": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "primary": "#89b4fa",
    "secondary": "#a6e3a1",
    "error": "#f38ba8",
    "warning": "#fab387",
    "success": "#a6e3a1",
    "border": "#313244",
    "selection": "#45475a",
    "inputBackground": "#181825",
    "inputForeground": "#cdd6f4",
    "codeBackground": "#181825",
    "linkColor": "#89b4fa"
  }
}

Load the theme in your config:

{
  "theme": "/path/to/my-theme.json"
}

Custom Keybinds

Override or add keybindings:

{
  "keybinds": [
    {
      "key": "ctrl+shift+p",
      "command": "commandPalette"
    },
    {
      "key": "alt+1",
      "command": "switchAgent",
      "args": { "agent": "build" }
    },
    {
      "key": "alt+2",
      "command": "switchAgent",
      "args": { "agent": "plan" }
    },
    {
      "key": "ctrl+enter",
      "command": "sendMessage"
    }
  ]
}

Available modifiers: ctrl, alt, shift, meta.

Available commands: commandPalette, sendMessage, insertNewline, cancelRequest, newSession, undo, redo, compact, exportSession, openEditor, listSessions, listModels, themeSelector, exit, switchAgent, scrollUp, scrollDown, scrollToTop, scrollToBottom, search, findNext.

Username Toggle

Toggle username display via the command palette:

Press Ctrl+P
Type "Toggle Username"
Press Enter

Alternatively, set it in tui.json:

{
  "showUsername": false
}

Troubleshooting

TUI Doesn't Render

If the TUI displays garbled output or doesn't render at all:

Ensure TERM is set correctly:
```
export TERM=xterm-256color
```
Run in pure mode:
```
opencode --pure
```

Check your terminal emulator supports true color:

echo $COLORTERM
# Should output: truecolor or 24bit

Use a recommended terminal (WezTerm, Alacritty, Ghostty, Kitty)

Keyboard Shortcuts Not Working

Some terminal emulators or window managers intercept certain key combinations:

Ctrl+X sequences may conflict with tmux (use Ctrl+X twice in tmux, or rebind in tui.json)
Alt keybinds may conflict with menu accelerators in some terminals
Ctrl+P for command palette may conflict with some shells

Use the command palette (Ctrl+P) as a fallback for any action.

Slow Performance

If the TUI feels sluggish:

Reduce scroll_speed in tui.json
Disable scroll_acceleration
Use /compact to compress long sessions
Start a fresh session with /new

What's Next

CLI Usage -- Non-interactive CLI, scripting, and automation
Web Interface -- Browser-based access
Configuration -- Configuration files reference
Customization -- Themes, keybinds, and providers

Starting the TUI​

Interface Layout​

Messaging​

Multi-line Messages​

File References with @​

Shell Commands with !​

Slash Commands​

Command Palette​

Keybinds​

Navigation​

Actions​

Agent Switching​

Search​

Agent Mode Switching​

Session Management​

Child / Parent Sessions​

Undo and Redo​

Session Details​

Start Fresh​

Editor Integration​

/editor Command​

/export Command​

Theme System​

TUI Configuration​

Example tui.json​

Options​

Attention Feature​

Image Support​

Customization​

Custom Themes​

Custom Keybinds​

Username Toggle​

Troubleshooting​

TUI Doesn't Render​

Keyboard Shortcuts Not Working​

Slow Performance​

What's Next​