Hoox — Edge-Native Algorithmic Trading on the Cloudflare Edge

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).

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

End User

Terminal UI (TUI)

🏁 Launching the TUI

⌨️ Global Keyboard Navigation

🗺️ All 15 Views

1. Dashboard (`Ctrl+1`)

2. Workers Overview (`Ctrl+2`)

3. Worker Detail (`Ctrl+3`)

4. Trade Monitor (`Ctrl+4`)

5. Logs Viewer (`Ctrl+5`)

6. Service Manager (`Ctrl+6`)

7. Config Editor (`Ctrl+7`)

8. Setup Wizard (`Ctrl+8`)

9. Settings (`Ctrl+9`)

10. Queue Depth (`Ctrl+0`)

11. KV Viewer (`Ctrl+Alt+K`)

12. Secrets Viewer (`Ctrl+Alt+S`)

13. AI Chat (`Ctrl+Alt+C`)

14. DB Query (`Ctrl+Alt+Q`)

15. Edge Topology (`Ctrl+Alt+E`)

🛜 Data channels

🛡️ Crash protection

🛠️ Troubleshooting

Next steps

​🏁 Launching the TUI

​⌨️ Global Keyboard Navigation

​🗺️ All 15 Views

​1. Dashboard (Ctrl+1)

​2. Workers Overview (Ctrl+2)

​3. Worker Detail (Ctrl+3)

​4. Trade Monitor (Ctrl+4)

​5. Logs Viewer (Ctrl+5)

​6. Service Manager (Ctrl+6)

​7. Config Editor (Ctrl+7)

​8. Setup Wizard (Ctrl+8)

​9. Settings (Ctrl+9)

​10. Queue Depth (Ctrl+0)

​11. KV Viewer (Ctrl+Alt+K)

​12. Secrets Viewer (Ctrl+Alt+S)

​13. AI Chat (Ctrl+Alt+C)

​14. DB Query (Ctrl+Alt+Q)

​15. Edge Topology (Ctrl+Alt+E)

​🛜 Data channels

​🛡️ Crash protection

​🛠️ Troubleshooting

​Next steps

🏁 Launching the TUI

⌨️ Global Keyboard Navigation

🗺️ All 15 Views

1. Dashboard (`Ctrl+1`)

2. Workers Overview (`Ctrl+2`)

3. Worker Detail (`Ctrl+3`)

4. Trade Monitor (`Ctrl+4`)

5. Logs Viewer (`Ctrl+5`)

6. Service Manager (`Ctrl+6`)

7. Config Editor (`Ctrl+7`)

8. Setup Wizard (`Ctrl+8`)

9. Settings (`Ctrl+9`)

10. Queue Depth (`Ctrl+0`)

11. KV Viewer (`Ctrl+Alt+K`)

12. Secrets Viewer (`Ctrl+Alt+S`)

13. AI Chat (`Ctrl+Alt+C`)

14. DB Query (`Ctrl+Alt+Q`)

15. Edge Topology (`Ctrl+Alt+E`)

🛜 Data channels

🛡️ Crash protection

🛠️ Troubleshooting

Next steps