[Terminal UI (TUI)]
Master reference for the full-screen terminal operations cockpit, keyboard shortcuts, view registries, and resilience engines.
The Hoox Terminal User Interface (TUI) is a full-screen, keyboard-driven operations cockpit built with OpenTUI, React 19, and Zustand. It provides real-time visibility into the edge trading mesh—workers, logs, trades, config, queues, KV, secrets, D1, and AI chat—without leaving the terminal.
Launching the TUI
# 1. Recommended: via the hoox CLI
hoox tui
# 2. Optional flags (forwarded as env to the renderer)
hoox tui --fps 60
hoox tui --no-mouse
# 3. Development: package entry
cd packages/tui && bun run dev
# 4. Built bundle
cd packages/tui && bun run build && bun run start
Requirements: Bun ≥ 1.2, 256-color terminal, minimum 80×24, OpenTUI installed via bun install.
Persistent UI state lives under $HOME/.hoox/.tui-state/ (session, crash log, chat history, DB query history).
⌨ Global Keyboard Navigation
| Shortcut | Action |
|---|---|
Ctrl+1 | Dashboard — system health overview |
Ctrl+2 | Workers Overview — 2-column worker cards |
Ctrl+3 | Worker Detail — metrics / logs / DOs / config (select a worker first) |
Ctrl+4 | Trade Monitor — live fills + positions + performance |
Ctrl+5 | Logs Viewer — filtered log stream |
Ctrl+6 | Service Manager — deploy / repair / kill-switch / edge map |
Ctrl+7 | Config Editor — TOML/JSON editor + validate |
Ctrl+8 | Setup Wizard — onboarding |
Ctrl+9 | Settings — preferences, check setup, fix |
Ctrl+0 | Queue Depth — backlog visualization |
Ctrl+Alt+K | KV Viewer — read-only KV browser |
Ctrl+Alt+S | Secrets Viewer — secret names only (never values) |
Ctrl+Alt+C | AI Chat — streaming agent chat |
Ctrl+Alt+Q | DB Query — read-only D1 SQL |
Ctrl+Alt+E | Edge Topology — graph-metadata mesh map |
Ctrl+P | Command palette (fuzzy) |
Ctrl+B | Toggle sidebar |
Ctrl+R | Refresh worker data |
Ctrl+Q | Quit (confirmation dialog) |
Esc | Close palette / dismiss modal |
Tab / Shift+Tab | Cycle focus |
Enter | Select / confirm |
Space | Toggle (e.g. pause trade feed) |
/ | Search (searchable views) |
If Ctrl+Q is swallowed by XON/XOFF flow control: stty -ixon, or use Ctrl+P → QUIT HOOX.
All 15 Views
1. Dashboard (Ctrl+1)
Service health grid, kill-switch status, auto-repair (hoox check fix), AI model health, alerts, quick stats (P&L, trades, AI calls).
2. Workers Overview (Ctrl+2)
2-column cards: status, uptime, CPU, memory, requests, DO count, edges. Enter opens Worker Detail. Actions: logs / deploy / repair via CLI bridge.
3. Worker Detail (Ctrl+3)
Four panes for the selected worker (select from Workers first): metrics, live logs, Durable Objects (names inferred from count), config preview (hoox config show with fallbacks).
4. Trade Monitor (Ctrl+4)
Live trade feed (SSE /trades/stream when API is up), open positions, today/7d/30d P&L, win rate, Sharpe. Space pauses the feed.
5. Logs Viewer (Ctrl+5)
Level + worker filters, text search, pause, fetch via hoox logs, export to ~/.hoox/logs-export-*.json. SSE /logs/stream when API is up.
6. Service Manager (Ctrl+6)
Per-worker deploy/repair, deploy-all, rebuild, kill-switch show/engage/disengage, interactive PoP-style edge map.
7. Config Editor (Ctrl+7)
File tree + TOML/JSON syntax highlighting, live validate (hoox config validate), format on demand.
8. Setup Wizard (Ctrl+8)
Guided onboarding (Cloudflare, exchanges, AI, strategies, Telegram) ending in deploy.
9. Settings (Ctrl+9)
Theme / notifications / refresh interval / shortcuts reference, Check Setup, Check Fix, config path display.
10. Queue Depth (Ctrl+0)
Queue backlog snapshot via hoox monitor queue-depth (auto-refresh while focused).
11. KV Viewer (Ctrl+Alt+K)
Read-only list + on-demand value reveal for non-secret keys (config kv list / get). Writes stay CLI-only.
12. Secrets Viewer (Ctrl+Alt+S)
Read-only names and metadata only — values are never fetched or shown.
13. AI Chat (Ctrl+Alt+C)
Streaming chat with agent worker models. History persisted under .tui-state/chat-history.json (Bun has no localStorage).
14. DB Query (Ctrl+Alt+Q)
Read-only SQL (SELECT / WITH / EXPLAIN only). Client-side validation + CLI enforcement. History under .tui-state/db-query-history.json.
15. Edge Topology (Ctrl+Alt+E)
Interactive map from monorepo graph-metadata.json (workers, infrastructure, communities, data flows). Resolves the file from CWD or monorepo root.
Data channels
| Channel | Role |
|---|---|
| HTTP | fetchWorkers + API when HOOX_API_URL is reachable |
| CLI bridge | Spawns hoox … for deploy, logs, config, queues, KV, secrets, D1, health |
| SSE | Trade + log streams (streamTrades / streamLogs) started after session restore when the API is available |
Connection state machine: connected → reconnecting → offline (status bar pills + expandable CLI error panel).
Crash protection
- Per-view ErrorBoundary — a broken view shows Retry; sidebar/status keep running.
- CrashRecoveryApp — process-level trap → Restart / Safe Mode / Report Bug →
$HOME/.hoox/.tui-state/crash.log.
Troubleshooting
| Symptom | Fix |
|---|---|
| Garbled prompt after exit | reset or tput reset |
| Ctrl+Q ignored | stty -ixon or command palette Quit |
| Layout broken | Resize to ≥ 80×24; export TERM=xterm-256color |
| OFFLINE forever | Start mesh / set HOOX_API_URL, ensure hoox on PATH |
| Topology empty | Run from monorepo root or bun run graph to refresh metadata |
Next steps
- Local Development — API / wrangler mesh that feeds the TUI
- CLI Reference — commands the TUI invokes
- TUI architecture (DevOps) — stores, backoff, crash model