TUI

Mosaic Terminal UI (tui)

Use mosaic tui when you want a chat-first full-screen terminal interface with sessions list, message stream, and live tool inspector.

Contract: interactive mode is full-screen TUI; non-interactive mode is one-shot via --prompt.

1. Start TUI

mosaic --project-state tui

2. Common startup options

# initial focus: messages|input|sessions|inspector
mosaic --project-state tui --focus sessions

# hide right inspector at startup
mosaic --project-state tui --no-inspector

# resume a specific session
mosaic --project-state tui --session <session_id>

# choose agent/profile as usual
mosaic --project-state --profile default tui --agent writer

3. Non-interactive one-shot

# script-friendly path, no fullscreen UI
mosaic --project-state tui --prompt "hello"

# JSON contract compatible one-shot
mosaic --project-state --json tui --prompt "hello"

If stdin/stdout is not a TTY and you don't provide --prompt, command returns a validation error.

4. Keyboard shortcuts

Enter: send message
Ctrl+J: insert newline
Tab: switch focus (messages/input/sessions/inspector)
Ctrl+N: start a new session
Ctrl+R: refresh sessions list
Ctrl+I: toggle inspector
?: help overlay
q or Ctrl+C: quit

5. Layout behavior

Wide terminal: left sessions + center messages + right inspector.
Narrow terminal: inspector auto-hidden.
Very narrow terminal: left panel collapses to compact top status line.

6. Troubleshooting

# check state path and writable status
mosaic --project-state directory --ensure --check-writable

# verify config/provider is healthy before opening TUI
mosaic --project-state status
mosaic --project-state health

Quickstart Sessions Guide Agents Guide Policy Guide Operations Troubleshooting Back to Guide Hub