TUI Tour

Running wayland-core with no prompt on a TTY opens the full-screen interactive terminal UI, built on ratatui 0.30. The TUI is the default run mode whenever stdout is a terminal and TERM is not dumb. Pass --no-tui to force the line-based REPL instead.

wayland-core          # opens the TUI
wayland-core --no-tui # plain REPL
wayland-core setup    # re-open the first-run onboarding screen

Surfaces

The TUI has ten surfaces. Six appear in the tab chrome at the top of the screen. Four are overlays or gates that sit in front of the active surface.

Tab chrome (six surfaces)

Tab label	Surface	Purpose
Workspace	`Workspace`	The main 3-pane conversation view
Sub-Agents	`SubAgents`	Live monitor for running sub-agents
Plan	`PlanReview`	Approve, keep, or discard the current plan
Config	`Config`	Settings editor
Plugins	`Plugins`	Plugin marketplace (install and remove)
Diagnostics	`Diagnostics`	Triptych of `/doctor`, `/cost`, and `/memory`

Navigate tabs with Tab (forward) and Shift+Tab (backward). These bindings are global: they work on any surface.

Non-tab surfaces

Surface	How to reach it
`Onboarding`	First launch, or `wayland-core setup` / `/setup`
`Palette`	Type `/` in the Workspace composer
`AgentNav`	`Alt+A` or `Ctrl+]` from Workspace
`AgentTranscript`	`Enter` on a row in AgentNav

Workspace surface

The Workspace is where you hold a conversation. It has three regions: the transcript, the right rail, and the composer.

Transcript

The transcript occupies the left portion of the body. It shows all turns in the conversation: user messages, assistant responses, system notices, tool requests and results, and the live streaming output for the current turn.

Scroll the transcript with PgUp and PgDn. When you scroll up, auto-scroll stops so you can read without the view jumping. The transcript shows a “jump to latest” hint at the bottom right; clicking it or scrolling back down re-arms auto-scroll.

Markdown in assistant responses is rendered by pulldown-cmark. Code blocks use syntect for syntax highlighting.

Tool cards

Each tool call appears as a card in the transcript. In Default and Auto-edit modes, tool calls that require approval show an interactive card where you choose to allow or deny. Cards can be expanded or collapsed: Ctrl+E toggles all visible cards between their compact summary and their full content view. When a tool is awaiting approval, Ctrl+F expands the card body so you can read a full diff or argument block before deciding.

Side rail

The right rail is 34 columns wide. It shows a path map of the files referenced in the session, the currently active tool list, and an activity feed. Below a terminal width of 100 columns the rail hides automatically to give the transcript the full width. Toggle it manually with Ctrl+B. The auto-hide does not change the Ctrl+B preference you set: the two interact independently.

Composer

The composer sits at the bottom of the Workspace. It is a tui-input field that expands to up to six input rows when multi-line content is pasted. The composer accepts @-references (see Command Palette and @-References) and slash commands.

Key	Action
`/`	Open the slash-command line
`Shift+Tab`	Cycle the approval mode (Default, Auto-edit, Force)
`Up`	Walk backward through input history
`Ctrl+B`	Toggle the side rail
`Ctrl+E`	Expand or collapse all tool cards
`PgUp` / `PgDn`	Scroll the transcript
`Ctrl+D`	Exit (only when the composer is empty)
`Ctrl+Space`	Toggle voice capture
`Alt+A` or `Ctrl+]`	Open the sub-agent list

Sub-Agents surface

The Sub-Agents surface shows all sub-agents that have been spawned in the current session: their names, statuses, and a live activity indicator. Press Enter on a row to open that agent’s live transcript. Press Esc to interrupt the spawn.

For a detailed look at sub-agent lifecycle and topology, see Sub-Agents and Swarm.

Plan surface

When plan mode is active, the engine produces a plan and pauses. The Plan surface shows the plan text and presents three choices:

Key	Action
`a`	Approve the plan and run it
`r`	Keep planning (return to the plan-mode loop)
`Esc`	Discard the plan

See Plan Mode for how to enter and exit the plan-mode loop.

Config surface

The Config surface is a live settings editor. Arrow keys move the cursor, Enter opens a setting, Space toggles a boolean, x reveals expert tuning fields, and Esc saves and closes. Changes write to the active config file immediately.

Plugins surface

The Plugins surface is the marketplace for installable plugins. Arrow keys select a row, Enter installs an available plugin or removes an installed one, i shows the details card for the selected plugin, and Esc closes the surface.

Diagnostics surface

The Diagnostics surface is a three-panel triptych: the doctor panel (key 1), the cost panel (key 2), and the memory panel (key 3). Press r to re-run the doctor checks. In the memory panel, d deletes the selected memory entry.

Global keybindings

These work on every surface:

Key	Action
`Esc`	Cancel, close, or go back
`Tab`	Next surface
`Shift+Tab`	Previous surface
`Ctrl+C`	Quit (two-press confirmation)
`?`	Show the help overlay

The two-press confirmation guard: the first Ctrl+C arms the guard and replaces the entire status bar with “Press Ctrl+C again to exit” in warning color. A second Ctrl+C exits. Anything else disarms the guard.

First-run onboarding

On first launch, or when invoked with wayland-core setup, the TUI opens on the Onboarding surface before showing the Workspace. The onboarding scans 13 environment variables for known provider API keys and offers to connect them by number. It also offers Ollama (no API key) and a read-only skip path. See Providers and Authentication for the key-prefix detection and validation details.