> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# 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

1. **Per-view ErrorBoundary** — a broken view shows Retry; sidebar/status keep running.
2. **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](local-development)** — API / wrangler mesh that feeds the TUI
* **[CLI Reference](../reference/cli-commands)** — commands the TUI invokes
* **[TUI architecture (DevOps)](/devops/tui)** — stores, backoff, crash model