OpenShell TUI Development Guide

Comprehensive reference for any agent working on the OpenShell TUI.

1. Overview

The OpenShell TUI is a ratatui-based terminal UI for the OpenShell platform. It provides a keyboard-driven interface for managing gateways, sandboxes, and logs — the same operations available via the openshell CLI, but with a live, interactive dashboard.

• Launched via: openshell term or mise run term
• Crate: crates/openshell-tui/
• Key dependencies:
  • ratatui (workspace version) — uses frame.size() (not frame.area())
  • crossterm (workspace version) — terminal backend and event polling
  • tonic with TLS — gRPC client for the OpenShell gateway
  • tokio — async runtime for event loop, spawned tasks, and mpsc channels
  • openshell-core — proto-generated types (OpenShellClient, request/response structs)
  • openshell-bootstrap — gateway discovery (list_gateways())
• Theme: Adaptive dark/light via Theme struct — NVIDIA-branded green accents. Controlled by --theme flag, OPENSHELL_THEME env var, or auto-detection.