Launch a full-screen interactive browser for exploring and installing agents. The TUI (Terminal User Interface) provides visual navigation, search, and batch installation.
Usage
Auto-launch
If you run the CLI without any command and your terminal supports TTY, the TUI launches automatically:
npx opencode-agents
# Automatically launches TUI in interactive terminals
Features
Visual Navigation
- Category tabs — Browse agents by category with keyboard or mouse
- Color-coded — Each category has a unique color for quick identification
- Agent cards — Name, description, tags, and install status
- Status indicators — ✓ installed, ⚠ outdated, ○ not installed
Keyboard Controls
| Key | Action |
|---|
↑ / ↓ | Navigate agent list |
← / → | Switch category tabs |
Tab | Next category tab |
Space | Toggle agent selection |
Enter | Install selected agents |
/ | Open search |
p | View pack details |
q / Esc | Quit or cancel |
h / ? | Show help |
Mouse Support
- Click tabs — Switch categories
- Click agents — Select for installation
- Scroll — Navigate long lists
- Click buttons — Install, cancel, quit
Search Mode
Press / to enter search:
- Type your query (e.g.,
docker, typescript, security)
- Results appear in real-time
- Navigate with
↑ / ↓
Space to select, Enter to installEsc to return to browse mode
Search matches agent names, descriptions, tags, and categories.
Pack Explorer
Press p to view predefined packs:
- Browse packs with
↑ / ↓
Enter to view pack details (agent list)Space to select entire packEnter again to install all agents in packEsc to return to main view
Installation States
Each agent shows its current state:
| Icon | State | Description |
|---|
| ✓ | Installed | File exists and hash matches lock |
| ⚠ | Outdated | File exists but hash mismatch |
| ○ | Not installed | File does not exist |
| ? | Unknown | File exists but no lock entry |
Flags
Overwrite existing agent files during installation. By default, the TUI skips already-installed agents.npx opencode-agents tui --force
Workflow Example
1. Launch TUI
2. Browse categories
┌─ OpenCode Agents ─────────────────────────────────────────┐
│ 💻 Languages │ 🤖 AI │ 🌐 Web │ 🗄️ Data │ ⚙️ DevOps │ ... │
├───────────────────────────────────────────────────────────┤
│ │
│ ✓ typescript-pro │
│ Modern TypeScript with strict mode, generics, and │
│ type safety │
│ Tags: typescript, types, generics, strict │
│ │
│ ○ python-pro │
│ Python 3.12+ with type hints, async patterns, and │
│ dataclasses │
│ Tags: python, async, typing, dataclasses │
│ │
│ ⚠ golang-pro │
│ Idiomatic Go with interfaces, goroutines, and error │
│ handling │
│ Tags: go, golang, concurrency, interfaces │
│ │
├───────────────────────────────────────────────────────────┤
│ ↑↓ Navigate │ Space: Select │ Enter: Install │ /: Search │
│ ←→ Tabs │ p: Packs │ q: Quit │
└───────────────────────────────────────────────────────────┘
3. Select agents
Press Space to toggle selection (✓ indicator appears next to agent name).
4. Install
Press Enter to install all selected agents. The TUI shows progress:
Installing 3 agents...
✓ python-pro → .opencode/agents/languages/python-pro.md
✓ golang-pro → .opencode/agents/languages/golang-pro.md (forced)
✓ rust-pro → .opencode/agents/languages/rust-pro.md
3 installed, 0 skipped, 0 failed
Press any key to continue...
5. Search mode
Press / and type docker:
┌─ Search: docker ──────────────────────────────────────────┐
│ │
│ ○ docker-specialist (devops) │
│ Multi-stage builds, BuildKit, networking, volumes, │
│ and security best practices │
│ │
│ ○ platform-engineer (devops) │
│ Internal platforms, developer experience, self- │
│ service infra, and golden paths │
│ │
├───────────────────────────────────────────────────────────┤
│ Found 2 agents │
│ Esc: Cancel │ ↑↓: Navigate │ Space: Select │ Enter: Install │
└───────────────────────────────────────────────────────────┘
Color Palette
Each category has a distinct color:
| Category | Color |
|---|
| Languages | Blue |
| AI | Purple |
| Web | Cyan |
| Data & API | Green |
| DevOps | Orange |
| DevTools | Yellow |
| Security | Red |
| MCP | Magenta |
| Business | Teal |
| Docs | Gray |
Requirements
- Node.js 20+ — Required for native ESM and built-in modules
- TTY terminal — The TUI requires an interactive terminal (not pipes or redirects)
- UTF-8 encoding — For box-drawing characters and emoji icons
- ANSI support — For colors and cursor control
The TUI automatically detects TTY support. If your terminal doesn’t support interactive mode, the CLI falls back to showing help text.
Architecture
The TUI is built with zero npm dependencies using Node.js built-ins:
- index.mjs — Lifecycle orchestration, main loop, signal handling
- screen.mjs — Terminal I/O (raw mode, flush, resize, input handling)
- input.mjs — Byte stream parser (raw bytes → ~20 action types)
- state.mjs — State machine (browse, search, confirm, installing, done, quit)
- renderer.mjs — Frame builder (state → ANSI string)
- ansi.mjs — ANSI codes, colors, box drawing, palettes
- list — Non-interactive agent listing
- search — Command-line search
- install — Direct installation without TUI
