TUI

Overview

The nikcli terminal UI is the default command registered by packages/nikcli/src/cli/cmd/tui/thread.ts. It is not only a renderer. The TUI is a split runtime: the main thread owns terminal input, OpenTUI rendering, dialogs, routes, and local process lifecycle, while a Bun worker owns the server app, project instances, SDK fetches, event streams, upgrades, and cleanup.

Visual tour

The captures on this page come from two sources: a recorded bun run --cwd packages/nikcli dev session run through a terminal-control PTY at 112×34 with the OpenTUI host profile, and live in-session dialogs opened during real workflows. Bundles, raw .termctrl recordings, accessibility trees, SVGs, PNGs and manifests live under artifacts/tui/tui-check/; the same skill powers the terminal-control docs.

Core shell

Empty home, slash-command autocomplete, and command palette — the surfaces reached before submitting a prompt.

In-app surfaces

Full-screen dialogs that the TUI renders on top of the shell: context-usage telemetry and analytics with KPIs, charts, gauges, and operational health badges.

Workspace view

The workspace route (type: "workspace", defined in context/route.tsx) is a four-tab panel that overlays any session. Each tab is registered as a hidden command in app.tsx (lines 714–787) and reachable from the command palette or as a slash command.

Default command

TuiThreadCommand is registered in packages/nikcli/src/index.ts before the one-shot run command. The command name is $0 [project], which makes it the default yargs route. It accepts project path, model, continue, session, prompt, and agent options, plus shared network flags from withNetworkOptions.

Worker model

The main process chooses NIKCLI_WORKER_PATH, the built worker file, or the local TypeScript worker source. It then starts a Bun Worker with a sanitized environment where Process.ROLE_ENV is worker and a run id is guaranteed. The worker calls Process.ensureMetadata("worker"), initializes logging, listens for global bus events, and exposes an RPC object.

Transport modes

The TUI has two runtime transports. Both use the generated SDK surface, but they differ in how requests and events reach the server app.

Renderer tree

packages/tui/src/app.tsx creates an OpenTUI renderer with a 45 FPS target, Kitty keyboard support, mouse support from TUI config, copy selection handling, and explicit Ctrl-C behavior. The Solid app is mounted inside an error boundary and a deep provider stack.

Feature plugins

Almost every surface the TUI shows — home tips, sidebar panels, the plugin manager, the wallpaper, the loop and mission managers — is a self-contained feature plugin under packages/tui/src/feature-plugins/, loaded through the same runtime that loads third-party plugins from npm. The larger ones follow the same layout: store.ts for reactive state, sdk.ts for typed SDK bindings, runner.ts for the local control plane, and dialogs.tsx for the Solid components.

Each plugin's commands, slash aliases, KV keys and internals are documented in TUI feature plugins.

Dialogs

All dialogs live in packages/tui/src/component/ and are registered through the DialogProvider and the command palette. The full list (in addition to those in the top-level README):

Routes

The TUI route state lives in context/route.tsx. It is a Solid store initialized from NIKCLI_ROUTE when present, otherwise from the home route. Route changes are in-memory UI navigation, not browser history.

The app keeps a mutable plugin route map and a reactive route key. When plugin routes change, the key is bumped so the route switch re-renders. Missing plugin routes render PluginRouteMissing with a home navigation action instead of crashing the TUI.

Commands and keybinds

CommandProvider owns the command registry. Components register command options with titles, descriptions, optional keybind names, optional slash aliases, categories, visibility, and an onSelect callback. The registry deduplicates by category plus value, merges local and global registrations, and exposes command palette, slash, and trigger APIs.

Dialogs

The TUI ships a few session-scoped dialogs that are useful to keep open while running long work. They are reachable from the command palette and as slash commands.

Context usage

DialogUsage (app.tsx line 1074) shows how the active session is spending its 1.0 M-token context window. The dialog breaks the window into used / free / reserved slices, plots a tokens-per-turn sparkline over the last 77 turns, surfaces the top token sources (system prompt, tools, skills, conversation, plus per-tool contributions from opentui, terminal-control, generate_image, browser, etc.), and ends with a four-card Context health strip (Usage, Cache, Headroom, Fragmentation).

Analytics

DialogAnalytics (app.tsx line 1086) is a 6-tab dashboard loaded through AnalyticsProvider against the host's /analytics/* HTTP endpoints. The Overview tab shows sessions, messages, cost, tokens with deltas vs. the prior window, the last-30-day token and cost histograms, the usage-composition stack (input / output / cache / reasoning), and the four-card Operational health strip (Activity, Tools, Background, Workspaces). Tabs 2 Tokens, 3 Models, 4 Tools, 5 Projects, 6 Sessions drill into each slice; cycle with tab or 1–6.

Event flow

SDKProvider creates a generated SDK client and an event emitter keyed by event type. It batches event delivery inside Solid batch calls, flushing immediately unless another flush happened in the last 16 milliseconds.

1. Direct mode passes a custom EventSource from thread.ts; the worker opens the SDK event stream and emits events over RPC.
2. HTTP mode calls sdk.event.subscribe directly and retries with exponential backoff from 250 ms to 5 seconds.
3. Queueing batches received events to keep bursty server updates from forcing one render per event.
4. TUI commands listen for tui.command.execute, tui.toast.show, and tui.session.select events and map them to local UI actions.
5. Cleanup aborts the SDK signal, active SSE controller, and pending flush timer on provider unmount.

Island plugin

The Island plugin is the CLI-side mirror of the macOS NikcliIsland.app notch UI. It writes a per-session JSON snapshot under ~/Library/Application Support/NikcliIsland/state.d/ on every relevant event, and the native app polls that directory to render live session state without keeping a separate IPC channel.

The bridge lives in @nikcli-ai/util/island-bridge and is self-activating: Bus.publish itself calls start() on first publish (idempotent, no-op after the first real call). That matters because the TUI's real session / bus activity runs inside a Worker thread with isolated module state — a listener registered only in the parent process would never see those events.

Each snapshot also carries the parent session id, agent title, project, cwd, the process pid, the local server port (when one is running), and a server URL — enough for the native app to call POST /permission/:requestID/reply directly when you approve a pending request from the notch.

# Inspect Island state
cat ~/Library/Application\ Support/NikcliIsland/state.d/nikcli-ses_abc.json

# Disable Island for this run without uninstalling the app
NIKCLI_ISLAND_DISABLE=1 nikcli

HTTP control routes

packages/nikcli/src/server/httpapi/tui.ts exposes routes that remote clients, companion surfaces, and automation can use to nudge the running TUI. Most routes publish a typed TuiEvent onto the bus. /tui/control is a queue bridge for request/response handoff.

Config and plugins

TUI-specific configuration is loaded by packages/nikcli/src/config/tui.ts. The loader reads global config directory files, NIKCLI_TUI_CONFIG, project TUI files, .nikcli config directories, and managed config. It migrates old TUI config, flattens nested tui objects, parses keybinds, deduplicates plugin specs, and records plugin metadata with local or global scope.

The TUI plugin API can register commands, plugin routes, and UI contributions. Runtime cleanup is tied to exit through TuiPluginRuntime.dispose(), so plugins should not depend on process exit for teardown.

Remote and attach

The TUI can either host its own local server for external access or attach to an existing server. nikcli attach <url> calls the same tui renderer with the provided URL instead of starting a local worker server. Remote Control uses TUI commands and server routes to drive the active prompt, sessions, scrolling, compacting, sharing, and interruption flows.

nikcli --port 4096 --hostname 127.0.0.1
nikcli attach http://127.0.0.1:4096
curl -X POST http://127.0.0.1:4096/tui/open-sessions
curl -X POST http://127.0.0.1:4096/tui/execute-command -H 'content-type: application/json' -d '{"command":"agent_cycle"}'

Operational checks

Use these checks when debugging TUI startup, remote control, or event delivery.

NIKCLI_TERMINAL=1 bun run dev
nikcli --print-logs --log-level DEBUG
nikcli --port 0 --hostname 127.0.0.1
nikcli attach http://127.0.0.1:4096
curl -i http://127.0.0.1:4096/global
curl -i -X POST http://127.0.0.1:4096/tui/open-help

Failure modes

Source anchors