10 — TUI

The terminal user interface: picasso with no command (or picasso tui) opens it. This page is the functional reference for what ships on main: how the screen is laid out, how you talk to a running turn, every key, every slash command, themes, motion and accessibility. The visual spec lives in design/ (design/INTEGRATION.md, design/Picasso TUI.html, design/styles.css); the internals are in tui-architecture.md.

Most TUI features also exist as a shell command (picasso <command>, most with a --json option; see apps/cli/README.md), and Picasso for Mac shares the same settings, themes, start page layout, project tiles and slash registry.

Tech stack

• Ink (React for terminals) on Node.js for layout, components and lifecycle.
• chalk + supports-color for colour, with a degraded ANSI fallback for restricted terminals.
• cli-truncate and string-width for wide-character-correct measurement.
• The slash registry and key bindings come from one manifest, packages/commands/command-manifest.json, which the TUI, the CLI help and the Mac command surface all read.

Launching

The first launch offers the tour (/tour): a short paged walk through asking, steering, reading and approving.

Layout

┌─────────────────────────────────────────────────────────────────────┐
│ picasso / auth-refactor                       GLM 5.2 @high   ● auto │  header
├─────────────────────────────────────────────────────────────────────┤
│  › tell me what changed in the auth module since main               │
│                                                                     │
│  I'll scan the auth module and compare against main.                │
│  ✓ Ran · Search for "auth"                     23 matches · 8 files │
│  ✓ Ran · Diff src/auth against main                  +47 / −12      │
│                                                                     │
│  Three meaningful changes since main: …                             │
├─────────────────────────────────────────────────────────────────────┤
│ ›  Ask anything. @ files, $ skills, / commands                      │  composer
│    New worktree · ⎇ auth-refactor · auto                            │  quiet line
├─────────────────────────────────────────────────────────────────────┤
│ ◇ SPONSORED   Linear — Built for software teams.  linear.app/picasso│  sponsor
│ tools 3   ctx 12.4K / 200K   cache 3.2K · 41%   ● auto     ● ready  │  status line
└─────────────────────────────────────────────────────────────────────┘

Top to bottom: header (project / thread breadcrumb, model and effort, mode badge) → transcript → composer with its quiet line (checkout, branch, permission) → sponsor line → status line. ctrl+b opens the sidebar and ctrl+d the details pane; /studio pins the sidebar open.

Start page

A new session opens on the start page, laid out like Picasso for Mac's Studio:

• A greeting and date ("Good evening · Sunday, November 8 at 10:40 PM") and the headline "What should we build in ‹project›?"; /new --no-project starts without a project.
• Activity: a labelled heatmap of your threads (months, Mon/Wed/Fri, a Less/More legend, "N threads in 2026"). /activity [year] pages through years.
• GitHub activity: your GitHub or GitLab contributions from the connected repo host, cached for an hour and hidden when no host is connected (/activity github [year]; connect one with /project connect).
• Recent threads, ending with one "This month" line (threads, change against last month, files changed).
• /customize shows, hides and reorders these sections and places the sponsor line above or below them; the layout is stored in the shared settings.startPage, so the Mac Studio follows it.

Every project wears the same generic initials tile as on the Mac (AuraOne → AO, picasso → P, my-web-app → MW) in one of ten distinct palette colours; Picasso never reads images out of your project folders.

Talking to a running turn

• Enter sends when idle. While a turn runs, Enter queues your message by default; the "While a turn is running, Enter…" setting (enterWhileRunning: queue or steer, also picasso settings set enterWhileRunning steer) flips it.
• Steer (ctrl+enter, alt+enter) sends the message into the running turn now. Steered messages show in the transcript as your own message, prefixed "› steered".
• Enter in an empty composer sends a queued message now: it steers the selected queued message (or the oldest) into the running turn. Queued rows read "queued · Enter sends now".
• Interrupt (ctrl+q) stops the current step and sends your draft at once. Stop is esc esc; ctrl+c cancels.
• The queue is editable and reorderable: ↑ selects it, e edits, s steers, x removes, shift+↑/↓ reorders. A paused queue offers Send next.
• Long pastes fold into a "pasted N lines" chip; ctrl+o opens the pasted text in a pager. ctrl+v attaches a clipboard image; @ attaches files; $ picks a skill.
• Links in the transcript are clickable in terminals that support OSC 8.

Rows in the transcript

• Live step rows read as what they do: "Running · <title>" while in flight, "Ran · <title>" when done. A shell command that exits non-zero shows ✕, not ✓. Tool results read as text, never raw JSON.
• Decisions: when one turn asks two or more things, they show as one numbered block ("Needs you · N decisions · answer each with its number; …"). Approvals take 1/2/3 (Allow, Allow for this thread, Deny; a/s/d still work).
• Options: when the agent calls present_options, the TUI shows a numbered list of two to four options (←/→ or n/p move, o opens one, a number picks it).
• ask_user_question and plan review reach you as questions; answer inline.
• Goal rounds show as "Goal round N of M" cards, live and after /resume.
• Progress reports arrive about every 10 minutes on long tasks (setting progressReports).
• Failed turns read "503 · <message>"; engine exit reasons are shown with secrets redacted.
• /fork, /undo and /rewind say where you are: "You're now in the fork; the original is unchanged. Back to the original: /continue <id8>".

Background processes

/tasks lists the session's background processes with a human title (the agent's description, or a summary of the command), a status ("Running · 2m", "Completed · 3s", "Failed · exit 1 · 8s", "Stopped") and the folder; they group Running → Failed → Completed, and Completed folds past five. /tasks kill <jobId> stops one. Picasso for Mac shows the same list in the inspector.

Resume picker

/sessions (and /continue with no id) groups threads like the Mac sidebar: Needs you (approvals and questions), Working, Recent, Settled. In the picker e archives a thread and u undoes the archive; f forks, p pins, d shows the diff, r resumes.

Keyboard

The full list is in ? (help) and comes from packages/commands/command-manifest.json.

Composer editing follows readline: ctrl+a/ctrl+e line start/end, alt+←/→ by word, ctrl+k/ctrl+u delete to end/start, ctrl+w delete word, ctrl+y paste deleted text, ctrl+z/ctrl+shift+z undo/redo. /vim turns on modal editing.

Slash commands

All 83 commands in packages/commands/command-manifest.json, grouped. Type / for the palette (fuzzy search) or /help for the same list in the terminal. Aliases are in brackets.

Conversation and runs

Sessions, history and files

Code and git

Models, providers and context

Permissions and safety

Agents, extensions and background work

Start page, look and terminal

Help and upkeep

/model <id> @<effort> sets the reasoning effort for any built-in model, and /model connections manages the ordered model connections with automatic fallback (see 07-providers.md). /schedule is an alias of /schedules; schedules need a runner and say how to turn one on (picasso service install, or "Keep threads running when Picasso quits" in Picasso for Mac). /settings shows "Keep threads running when Picasso quits: on/off".

Status line

Always visible, always honest. Values come from the latest session events, never from fixtures.

• `tools`: tool calls this turn.
• `ctx`: current tokens / context window, e.g. 12.4K / 200K.
• `cache`: cached input tokens and hit share, e.g. 3.2K · 41%. Dollar costs are never rendered (ad-supported product); budget state shows as a share of the cap.
• `mode`: the permission mode badge (safe, auto, yolo, paranoid, plan, goal).
• `branch`: the current git branch (⎇).
• `mi`: on wide terminals, a compact managed-inference summary; hidden on narrow ones so the core segments never wrap.
• `state`: ready, busy (with a pulse), paused or error.

/context shows the context window with recorded cache sections; /context timeline shows what entered the context turn by turn (additions, compaction, cache hit/miss per step, subagent lanes; "No usage reported" or "Size not recorded" when the engine did not report it). /usage shows tokens and cache for the session and today.

Sponsor line

One line, above the status line, always labelled ◇ SPONSORED (ASCII fallback <>). One sponsor per session, no mid-session rotation, shown in every permission mode including paranoid, never dismissable, never inside the conversation or model output. The URL is printed and selectable; /ads why explains why you see it. Allow/deny lists are in 13-ads-monetization.md.

Themes

Thirteen colour themes, shared with Picasso for Mac: Picasso (the default), Catppuccin Latte, Catppuccin Mocha, Gruvbox Light, Gruvbox Dark, Nord, Solarized Light, Solarized Dark, Tokyo Night, Rosé Pine, One Dark, GitHub Light and GitHub Dark. /theme opens the picker, /theme <id> sets one, /theme duplicate <id> [name] makes a custom copy in <PICASSO_HOME>/themes/*.json; picasso settings set theme <id> does the same from the shell. Every terminal colour meets WCAG AA contrast.

Two overlays work with any theme: the colour-blind diff palette (/colorblind, --theme colorblind or PICASSO_COLORBLIND=1) swaps add/delete to blue/orange, and --theme high-contrast raises the faint text tones. /dark returns to the dark theme.

Motion and accessibility

• Animation is limited to the caret, the braille spinner on running rows and a pulse on live goal rounds and the sponsor's first appearance.
• Reduced motion: --no-animation, PICASSO_REDUCED_MOTION=1, or Settings › Appearance › motion (full / reduced) in /settings, remembered across launches. Spinners become static marks and the pulse a static dot.
• Accessible mode: --accessible or PICASSO_A11Y=1: no motion, no box art, plain links, a linear transcript a screen reader can follow.
• Every action is reachable by keyboard; the mouse is an enhancement only.

Terminals and fallbacks

First-class: iTerm2, WezTerm, Kitty, Ghostty, Alacritty, Windows Terminal (24-bit colour, Unicode box drawing, braille spinners).

Narrow terminals (under 80 columns) collapse to one column with tool summaries only; very narrow ones (under 60) show a one-time note. picasso doctor checks the terminal, and picasso terminal-graphics checks inline image support.

Design rules

1. One accent colour per theme; semantic accents (memory, goal, plan, sponsor) are the only other saturated colours.
2. The sponsor is one line, above the status line, always labelled.
3. Tool rows collapse to one line after completion; they are not log dumps.
4. The status line is real: real token counts, real cache and budget share, never a dollar cost.
5. Reduced motion disables all animation.
6. No emoji in product copy. Glyphs are ◆ ◇ ▾ ● ○ › ✓ ✕.
7. Errors say what to do, e.g. "Run picasso auth login to refresh."

Dependencies

• packages/tui: Ink components mirroring design/tui-primitives.jsx.
• packages/commands: the slash registry and key bindings.
• packages/core: the engine session and event stream.
• packages/shared-home: themes and settings shared with the Mac.
• packages/ads-sdk: sponsor content.
• design/styles.css: the token source.