mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
10 KiB
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:
- Drag and drop any image file into the terminal
- OpenCode automatically adds it to the prompt
- 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+Kto 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
Tabkey switching between Plan and Build modes. This single habit will dramatically improve your OpenCode workflow efficiency.
📚 What's Next?
- Agents Guide - Work with AI agents
- Skills Guide - Create reusable workflows
- Workflows Guide - Design development workflows
- Back to Main Guide
Last updated: February 2026