# Tui Development

Guide for developing the OpenShell TUI, a ratatui-based terminal UI for the OpenShell...

- Repository: https://github.com/NVIDIA/OpenShell (20903 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add NVIDIA/OpenShell --skill tui-development -g -a claude-code -y`
Codex: `npx skills add NVIDIA/OpenShell --skill tui-development -g -a codex -y`
Cursor: `npx skills add NVIDIA/OpenShell --skill tui-development -g -a cursor -y`
Gemini CLI: `npx skills add NVIDIA/OpenShell --skill tui-development -g -a gemini-cli -y`

## Description

Guide for developing the OpenShell TUI, a ratatui-based terminal UI for the OpenShell platform. Covers architecture, navigation, data fetching, theming, UX conventions, and development workflow. Trigger keywords - term, TUI, terminal UI, ratatui, openshell-tui, tui development, tui feature, tui bug.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.area()` for the drawable terminal 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.

## 2. Domain Object Hierarchy

The data model follows a strict hierarchy: **Gateway > Workspace > Sandboxes/Providers/Settings > Logs**.

The rest: https://github.com/NVIDIA/OpenShell/blob/HEAD/.agents/skills/tui-development/SKILL.md