Files
opencode-primer/docs/TUI-MASTERY.md
T

10 KiB

TUI Mastery Guide

🎯 Overview

OpenCode's Terminal User Interface (TUI) is where the magic happens. This guide covers everything you need to master the TUI for maximum productivity.

🖥️ TUI Layout Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│ OpenCode v1.5.2 │ Project: /Users/you/project │ Model: gpt-5.2-codex        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│ You: Can you help me fix the bug in @src/utils/validation.ts?               │
│                                                                             │
│ OpenCode: I'll analyze the validation.ts file and identify the bug...       │
│                                                                             │
│ [Thinking...]                                                               │
│ • Reading file: src/utils/validation.ts                                     │
│ • Analyzing validation logic...                                             │
│ • Found potential issue on line 45...                                       │
│                                                                             │
│ The bug is in the email validation regex. Here's the fix:                   │
│                                                                             │
│ ```typescript                                                               │
│ // Before:                                                                  │
│ const emailRegex = /^[^@]+@[^@]+\.[^@]+$/;                                  │
│                                                                             │
│ // After:                                                                   │
│ const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;      │
│ ```                                                                         │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│ [Build] Press Tab to switch agents • Type /help for commands • Ctrl+C to exit│
└─────────────────────────────────────────────────────────────────────────────┘

⌨️ Essential Keyboard Shortcuts

Shortcut Action Description
Tab Switch agents Toggle between Build and Plan modes
Ctrl+C Exit Exit OpenCode (press twice to force)
Ctrl+R Redo Redo last undone change
Ctrl+U Undo Undo last change
Ctrl+L Clear Clear terminal screen
Ctrl+K Search Search command history
↑/↓ History Navigate command history
@ File search Fuzzy search for project files
! Shell prefix Execute shell command
/ Command mode Enter slash command mode
Esc Cancel Cancel current operation

📁 File Reference System (@ Syntax)

OpenCode's @ syntax revolutionizes how you reference files:

Basic File Reference:

# Reference a specific file
Can you explain the authentication logic in @src/auth/index.ts?

# Fuzzy search - OpenCode will help you find the file
I need to update the configuration in @config

Multiple File References:

# Compare two files
Compare the implementation in @src/old-impl.ts and @src/new-impl.ts

# Analyze entire directory
What's the structure of @src/components/?

Line-Specific References:

# Reference specific lines
Check lines 45-60 in @src/utils/validation.ts

# Error location
There's an error on line 123 in @src/api/server.ts

💻 Shell Command Integration

Execute shell commands directly within OpenCode:

Basic Shell Commands:

# Run any shell command with ! prefix
!ls -la
!git status
!npm install
!docker ps

Command Output in Context:

# Use command output in your prompt
!pwd
# OpenCode sees: "/Users/you/project"

Now create a new directory here called "tests"

Chaining Commands:

# Multiple commands
!git status && !git diff

# Capture output for analysis
!cat package.json | grep version
What version of React are we using based on the output above?

🖼️ Image Analysis

OpenCode can analyze images dragged into the terminal:

Using Images:

  1. Drag and drop any image file into the terminal
  2. OpenCode automatically adds it to the prompt
  3. Reference the image in your queries

Example Workflow:

# 1. Drag UI mockup into terminal
# 2. OpenCode detects: [Image #1: dashboard-mockup.png]

Create a React component that matches this design [Image #1]

Supported Image Types:

  • PNG, JPEG, GIF, WebP
  • Screenshots, mockups, diagrams
  • UI designs, architecture diagrams

🔄 Agent Switching (Build vs Plan)

OpenCode's dual-agent system is its secret weapon:

Plan Mode (Read-Only):

  • Activate: Press Tab (shows [Plan] in status bar)
  • Purpose: Analyze, plan, brainstorm without making changes
  • Use Case: "How would you implement this feature?"

Build Mode (Read-Write):

  • Activate: Press Tab (shows [Build] in status bar)
  • Purpose: Make actual code changes
  • Use Case: "Go ahead and implement the plan"

Workflow Example:

# Start in Plan mode (default)
[Plan] How would you add dark mode to this React app?

# Review the plan, ask questions
What about CSS variables vs Tailwind?

# Switch to Build mode (Tab)
[Build] Sounds good! Implement it.

💬 Conversation Management

Session Persistence:

  • Conversations are automatically saved
  • Resume where you left off
  • Git-based undo/redo system

Multiple Sessions:

# List sessions
/sessions

# Switch sessions
/sessions switch session-name

# Delete session
/sessions delete old-session

Export Conversations:

# Export to markdown
/export

# Creates: opencode-conversation-2025-02-26.md

⚡ Advanced TUI Features

1. Compact Mode:

# Summarize long conversations
/compact

# Focus on specific topics
/compact "Focus on the authentication changes"

2. Editor Integration:

# Open external editor for long messages
/editor

# Uses $EDITOR environment variable

3. Theme Customization:

# Change TUI theme
/themes

# Select from available themes
# Popular: catppuccin, dracula, nord, solarized

4. Real-time Cost Display:

  • Token usage shown in status bar
  • Cost estimates for current session
  • Provider-specific pricing

🚀 Productivity Tips

1. Quick File Navigation:

# Use @ with partial names
@utils  # Finds utils/ directory or utils.ts
@.env   # Finds .env files
@test   # Finds test files

2. Command History:

  • Press ↑ to cycle through previous commands
  • Ctrl+K to search history
  • History persists across sessions

3. Multi-line Input:

# Shift+Enter for new lines
This is a multi-line
query that spans
multiple lines

4. Quick Provider Switching:

# Change model on the fly
/models

# Select from list
# Changes apply immediately

🛠️ Troubleshooting TUI Issues

Common Issues:

1. TUI not rendering properly

# Check terminal compatibility
echo $TERM

# Try different terminal emulator
# WezTerm or Alacritty recommended

2. Input lag or slow response

# Check system resources
!top

# Try lighter model
/models
# Select smaller model

3. Images not working

# Check terminal image support
# Use WezTerm for best image support

# Alternative: describe image in text

4. File references not found

# Check current directory
!pwd

# Use absolute paths if needed
@/full/path/to/file.ts

Performance Optimization:

# Use lighter themes
/themes
# Select "minimal" or "simple"

# Disable thinking steps
/thinking off

# Reduce verbosity in agent settings

🎨 TUI Customization

Keybind Customization:

// ~/.config/opencode/keybinds.json
{
  "switch_agent": "Tab",
  "exit": ["Ctrl+C", "Ctrl+D"],
  "clear": "Ctrl+L",
  "history_search": "Ctrl+K"
}

Theme Configuration:

// ~/.config/opencode/themes.json
{
  "current": "catppuccin",
  "custom": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "accent": "#89b4fa"
  }
}

Status Bar Customization:

// ~/.config/opencode/config.json
{
  "ui": {
    "status_bar": {
      "show_cost": true,
      "show_tokens": true,
      "show_model": true,
      "show_agent": true
    }
  }
}

🎯 Mastery Checklist

  • Can switch between Plan and Build modes with Tab
  • Know how to reference files with @ syntax
  • Can execute shell commands with ! prefix
  • Understand how to use image analysis
  • Know essential keyboard shortcuts
  • Can manage conversations and sessions
  • Know how to troubleshoot common issues
  • Have customized TUI to personal preferences

💡 Pro Tip: Master the Tab key switching between Plan and Build modes. This single habit will dramatically improve your OpenCode workflow efficiency.


📚 What's Next?


Last updated: February 2026