TUI Reference

Layout

┌─ Toporic v0.2.0  [AUTO]  ⣾ Thinking…  █████░░░░░ 53%  $0.0123 ─┐  ← title bar
│ ┌ Chat ────────────────────────────┐ ┌ Sidebar ──────┐ │
│ │ You: hello                        │ │ ~/proj:main    │ │
│ │                                   │ │ ────────────  │ │
│ │ Assistant: Hi! How can I help?    │ │ ▼ Tasks        │ │
│ │                                   │ │   ✓ Add l…     │ │
│ │ ── Reasoning ────────────────╯    │ │   • Refact…    │ │
│ │  Let me think through the appr…   │ │   [ ] Write…   │ │
│ │                                   │ │ ▼ Files        │ │
│ │ ▸ run_command(cargo test)  ✓  1.2s│ │  +12 -3 src/…  │ │
│ │                                   │ │  +5  -0 test…  │ │
│ │                                   │ │                │ │
│ │                                   │ │                │ │
├─┴───────────────────────────────────┴────────────────┴──────────┤
│ ┌ Input ─────────────────────────────────────────────────────┐ │  ← input box
│ │ ❯ tell me about the project                                │ │
│ └────────────────────────────────────────────────────────────┘ │
├─ new │ enter:send  tab:mode  ctrl+p:palette  ctrl+b:sidebar ───┤  ← footer
└─────────────────────────────────────────────────────────────────┘

The layout adapts automatically:

Title bar — app name, version, mode ([PLAN] / [AUTO] / [BUILD]), spinner, status, token gauge with percentage and cost, git branch
Sidebar — toggled with Ctrl+B, appears to the right of the chat area (shown only when terminal >= 100 columns wide); 35 columns wide with collapsible sections
Chat area — messages, reasoning blocks, tool calls, streaming content
Input box — multiline text entry with history (up to 5 visible lines)
Footer — session status, keyboard hints, workspace:branch
Diagnostics panel — toggle with Ctrl+L (8-line panel at bottom)

Title bar

The title bar shows real-time session information:

Element	Description
`Toporic v0.2.0`	App name and version
`[PLAN]` / `[AUTO]` / `[BUILD]`	Current permission mode
`⣾ Thinking…`	Braille spinner during LLM generation
`⣾ run_command…`	Tool name during tool execution
`█████░░░░░ 53%`	Token usage gauge (green < 50%, yellow 50–80%, red > 80%)
`$0.0123`	Estimated API cost (4 decimal places for < $0.01)
`main`	Current git branch

During context compaction, the title bar shows a pulsating “Compacting…” indicator.

Input box

Type normally to compose a message
Enter — submit
Shift+Enter, Ctrl+J, or Alt+Enter — insert a newline (multiline, up to 5 visible lines)
Up/Down (when input is empty) — navigate 50-entry command history
Up/Down (when multiline) — move cursor between input lines
Left/Right — move cursor within the current line
Home/End — jump to line start/end
Ctrl+A / Ctrl+E — jump to line start/end
Ctrl+W — delete word backward
Ctrl+V — paste from clipboard
Ctrl+C — copy input text
Esc — clear input / close popup / cancel

During streaming, character keys are buffered (type-ahead) and replayed into the input box when the agent finishes.

Keybindings

Global (always available)

Key	Action
`Ctrl+B`	Toggle sidebar visibility
`Ctrl+L`	Toggle diagnostics panel
`Ctrl+N`	Start a new session
`Ctrl+P`	Open command palette
`Ctrl+,`	Open config overlay (provider/model/theme/language)
`Tab`	Cycle permission mode: PLAN → AUTO → BUILD
`Ctrl+C`	Quit (idle) / Cancel current stream (streaming)
`Ctrl+End`	Force scroll to bottom, resume auto-follow
`PageUp`	Scroll chat up 10 lines (pauses auto-scroll)
`PageDown`	Scroll chat down 10 lines

Input focus

Key	Action
`Enter`	Submit input
`Shift+Enter` / `Ctrl+J` / `Alt+Enter`	Insert newline
`Ctrl+W`	Delete word backward
`Ctrl+A`	Jump to line start
`Ctrl+E`	Jump to line end
`Ctrl+V`	Paste from clipboard
`Ctrl+C`	Copy input text to clipboard
`Esc`	Clear input
`Up` / `Down`	Input history (when empty) or navigate lines (when multiline)
`Left` / `Right`	Move cursor
`Home` / `End`	Jump to line start/end
`Backspace`	Delete char before cursor
`Delete`	Delete char after cursor

Message focus (press `Tab` to cycle from Input)

Key	Action
`Up` / `k`	Scroll up 1 line
`Down` / `j`	Scroll down 1 line
`PageUp` / `PgUp`	Scroll up 10 lines
`PageDown` / `PgDn`	Scroll down 10 lines
`Enter` / `Space`	Expand/collapse focused tool call
`End` / `G`	Jump to bottom, resume auto-scroll
`Home` / `g`	Jump to top
`Esc`	Return focus to input

Sidebar focus (press `Tab` to cycle into)

Key	Action
`Up` / `Down`	Scroll 1 line
`PageUp` / `PgUp`	Scroll 30 lines
`PageDown` / `PgDn`	Scroll 30 lines
`j` / `k`	Scroll 1 line
`Esc`	Return focus to input

Overlays (Help, Popups, Confirm)

Key	Action
`↑` / `↓`	Navigate items / scroll
`PgUp` / `PgDn`	Scroll faster (10 lines)
`Enter`	Confirm selection
`Esc`	Go back / close overlay
`Y` / `y`	Confirm dialog: accept
`N` / `n` / `Enter` / `Esc`	Confirm dialog: reject

Command palette (`Ctrl+P`)

Press Ctrl+P to open a fuzzy-searchable list of all available actions. Start typing to filter. Available actions include:

Change provider, model, theme, or language
Start a new session
Toggle sidebar
Toggle diagnostics panel
Open help overlay
Resume a past session

Config overlay (`Ctrl+,`)

Press Ctrl+, to open the config overlay showing the current provider, model, theme, and language. Use ↑/↓ to select a field and Enter to open the corresponding picker popup. Press Esc to close.

Slash commands

Type / as the first character in the input box to open the slash command dropdown. The dropdown filters commands as you type. Press Tab to autocomplete the selected command or Enter to execute it directly.

Category	Commands
Help	`/help`, `/?`, `/exit`
Modes	`/plan`, `/auto`, `/build`
Session	`/session --new`, `/session list`, `/session <id>`
Config	`/provider`, `/provider <name>`, `/model`, `/model <name>`, `/theme <name>`, `/language <code>`
Skills	`/skill list`, `/skill <name>`, `/mcp`
Workspace	`/init`
Stats	`/usage`, `/tokens`

Tool calls

Tool calls appear in the message list as collapsible units:

Collapsed (default): ▸ command_name ✓ 1.2s (green check with elapsed time) or ▸ command_name ✗ (red cross)
Expanded: Shows the full tool arguments, a ─── Result ─── separator, and the full result content
Streaming: Last 5 active tool calls shown with spinner/checkmark/error icons and elapsed time

To expand: press Tab to focus the message list, then j/k to navigate to the tool call, and Enter or Space to toggle expansion. Press Esc to return focus to the input.

Reasoning display

When the LLM emits chain-of-thought / reasoning tokens (e.g. from DeepSeek R1 or Anthropic extended thinking), they appear as dim italic text in the chat area with a collapsible header:

── Reasoning ╰╯
Let me think through the approach...
(click to collapse)
── Reasoning ╰╮

Previous reasoning blocks are auto-collapsed when a new response starts.

Toggle: Ctrl+B (requires terminal >= 100 columns wide to appear)
Width: 35 columns
Auto-show: Opens automatically when tasks (todo items) are added
Sections (collapsible, toggle with Enter or click):
- Tasks — Todo list with status markers:
  - • / █ — in progress
  - ✓ — completed
  - ✗ — cancelled
  - [ ] — pending
- Files — Files modified in the current session with git diff stats (+additions -deletions)
Header: Workspace path (home shown as ~) and git branch (e.g. ~/proj:main)
Focus: Tab cycles through Input → Chat → Sidebar → Input; focused sidebar has accent-colored border

Diagnostics panel

Toggle with Ctrl+L. Shows a scrollable 8-line panel at the bottom with log output and diagnostic messages. Retains up to 1000 lines. Use ↑/↓ to scroll when focused.

Spinner and status

The title bar shows a braille spinner and status text:

State	Display
LLM is generating	`⣾ Thinking…`
Tool is executing	`⣾ tool_name…`
At auto-scroll position	Stable spinner (end of chat)
Custom status	`⣾ status message` (set by agent)
Compacting	Pulsating `Compacting…`

Auto-scroll

Enabled by default — new content scrolls into view automatically
Pause: scroll up manually (PageUp, Up, k)
Resume: press End or G (in message focus) or Ctrl+End
Type-ahead characters are buffered during streaming and replayed into the input box when the agent finishes

Help overlay

Press ? at any time (or type /?) to open the full keybinding and command reference. The overlay title reads Help ↓ ↑ as a reminder that you can scroll its contents. Press Esc to close.

Confirm dialog

Before executing mutating tools (run_command, write_file, edit_file, delete_file), Toporic shows a centered confirmation popup in Build mode:

╔══════════════════════════════════════╗
║  Allow tool execution?               ║
║                                      ║
║  run_command: cargo test             ║
║                                      ║
║  [Y] Yes    [N] No (default)         ║
║                    Esc=cancel        ║
╚══════════════════════════════════════╝

Y / y → accept
N / n / Enter / Esc / Ctrl+C → reject (default)

Themes

Three color themes are available, switchable via Ctrl+, or command palette:

Theme	Accent color	Style
Amber (default)	`#F59E0B`	Warm orange/yellow
Purple	`#7C6AF7`	Cool blue-purple
Green	`#34D399`	Emerald green

Themes apply to accents, borders, status markers, and role colors.

Welcome screen

When a new session starts with no message history, the TUI shows an ASCII art “TOPORIC” logo with quick-start tips: available commands, keybindings, and how to get started.

Internationalization

The TUI supports 8 languages, configurable via /language <code> or Ctrl+,:

Code	Language
`en`	English (default)
`zh-CN`	Simplified Chinese
`zh-TW`	Traditional Chinese
`ja`	Japanese
`ko`	Korean
`es`	Spanish
`fr`	French
`de`	German
`pt`	Portuguese

Translations cover footer hints, input placeholder, message bubbles, sidebar sections, popup dialogs, help text, and config labels.

Notifications (toasts)

Error, warning, and info toasts appear below the input area and auto-expire after 4 seconds. Up to 3 toasts are visible at once. Errors also trigger a red flash animation. Color-coded:

Info — blue
Warning — yellow
Error — red

Animations

The TUI uses subtle animations for transitions:

Message fade-in when appearing
Tool call slide-in from left
Sidebar slide-in from right / slide-out to right
Config overlay slide from top
Error flash (red sweep effect)
Token gauge fade-in