TUI (Terminal UI)

Quick start

Start the Gateway.

bash
mayros gateway

Open the TUI.

bash
mayros tui

Type a message and press Enter.

Remote Gateway:

bash
mayros tui --url ws://<host>:<port> --token <gateway-token>

Use --password if your Gateway uses password auth.

What you see

Header: connection URL, current agent, current session.
Chat log: user messages, assistant replies, system notices, tool cards.
Status line: connection/run state (connecting, running, streaming, idle, error).
Footer: connection state + agent + session + model + think/verbose/reasoning + token counts + deliver.
Input: text editor with autocomplete.

Mental model: agents + sessions

Agents are unique slugs (e.g. main, research). The Gateway exposes the list.
Sessions belong to the current agent.
Session keys are stored as agent:<agentId>:<sessionKey>.
- If you type /session main, the TUI expands it to agent:<currentAgent>:main.
- If you type /session agent:other:main, you switch to that agent session explicitly.
Session scope:
- per-sender (default): each agent has many sessions.
- global: the TUI always uses the global session (the picker may be empty).
The current agent + session are always visible in the footer.

Sending + delivery

Messages are sent to the Gateway; delivery to providers is off by default.
Turn delivery on:
- /deliver on
- or the Settings panel
- or start with mayros tui --deliver

Pickers + overlays

Model picker: list available models and set the session override.
Agent picker: choose a different agent.
Session picker: shows only sessions for the current agent.
Settings: toggle deliver, tool output expansion, and thinking visibility.

Keyboard shortcuts

Enter: send message
Esc: abort active run
Ctrl+C: clear input (press twice to exit)
Ctrl+D: exit
Ctrl+L: model picker
Ctrl+G: agent picker
Ctrl+P: session picker
Ctrl+O: toggle tool output expansion
Ctrl+T: toggle thinking visibility (reloads history)

Slash commands

Core:

/help
/status
/agent <id> (or /agents)
/session <key> (or /sessions)
/model <provider/model> (or /models)

Session controls:

/think <off|minimal|low|medium|high>
/verbose <on|full|off>
/reasoning <on|off|stream>
/usage <off|tokens|full>
/elevated <on|off|ask|full> (alias: /elev)
/activation <mention|always>
/deliver <on|off>

Session lifecycle:

/new or /reset (reset the session)
/abort (abort the active run)
/settings
/exit

Other Gateway slash commands (for example, /context) are forwarded to the Gateway and shown as system output. See Slash commands.

Local shell commands

Prefix a line with ! to run a local shell command on the TUI host.
The TUI prompts once per session to allow local execution; declining keeps ! disabled for the session.
Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent cd/env).
A lone ! is sent as a normal message; leading spaces do not trigger local exec.

Tool output

Tool calls show as cards with args + results.
Ctrl+O toggles between collapsed/expanded views.
While tools run, partial updates stream into the same card.

History + streaming

On connect, the TUI loads the latest history (default 200 messages).
Streaming responses update in place until finalized.
The TUI also listens to agent tool events for richer tool cards.

Connection details

The TUI registers with the Gateway as mode: "tui".
Reconnects show a system message; event gaps are surfaced in the log.

Options

--url <url>: Gateway WebSocket URL (defaults to config or ws://127.0.0.1:<port>)
--token <token>: Gateway token (if required)
--password <password>: Gateway password (if required)
--session <key>: Session key (default: main, or global when scope is global)
--deliver: Deliver assistant replies to the provider (default off)
--thinking <level>: Override thinking level for sends
--timeout-ms <ms>: Agent timeout in ms (defaults to agents.defaults.timeoutSeconds)

Note: when you set --url, the TUI does not fall back to config or environment credentials. Pass --token or --password explicitly. Missing explicit credentials is an error.

Theme system

Mayros ships with 10 built-in themes. Switch at any time with /theme:

bash
/theme dark              # Default dark theme
/theme light             # Light theme
/theme high-contrast     # High visibility
/theme dracula           # Dracula color scheme
/theme github-dark       # GitHub Dark
/theme github-light      # GitHub Light
/theme solarized-dark    # Solarized Dark
/theme solarized-light   # Solarized Light
/theme atom-one-dark     # Atom One Dark
/theme ayu-dark          # Ayu Dark

Themes apply to all TUI elements: chat log, tool cards, markdown rendering, editor, settings panel, and select lists. The current theme persists in config under ui.theme.

Keybinding customization

Default keybindings can be overridden in config under ui.keybindings:

Action	Default	Description
`selectAgent`	Ctrl+G	Open agent picker
`selectModel`	Ctrl+L	Open model picker
`selectSession`	Ctrl+P	Open session picker
`toggleTools`	Ctrl+O	Toggle tool output
`toggleThinking`	Ctrl+T	Toggle thinking display
`toggleVim`	Ctrl+Shift+V	Toggle vim mode

json5
{
  ui: {
    keybindings: {
      selectAgent: "ctrl+a",
      selectModel: "ctrl+m"
    }
  }
}

Vim mode

Enable vim-style editing with /vim or Ctrl+Shift+V:

Normal mode: motions (h, j, k, l, w, b, 0, $), operators (d, c, y with count prefix), commands (x, D, C, p, u, dd, cc, yy)
Insert mode: standard text input, Escape returns to normal mode
Mode switches: i, a, I, A, o, O
Mode indicator shows -- NORMAL -- or -- INSERT -- in the status line
50-item undo stack (u in normal mode)

Persist vim mode in config: ui.vim: true.

@ File mentions

Type @ followed by a filename to trigger enriched autocomplete. The provider queries Cortex for matching symbols (functions, classes, files) and merges them with filesystem suggestions.

Pattern: @partial-name triggers symbol lookup
Results are cached (LRU, max 50 entries, 30s TTL)
Non-blocking: queries fire asynchronously, results appear on next keystroke

Diff viewer

View diffs inline with /diff:

bash
/diff                    # Show current git diff

Diffs are rendered with color coding: green for additions, red for deletions, cyan for hunk headers. Stats show +N -N (F files).

Context visualization

Check token usage with /context:

bash
/context                 # Show context window usage

Displays a progress bar with color-coded fill (green < 70%, yellow < 90%, red >= 90%) plus token breakdown (input, output, free).

Output styles

Switch response styles with /style:

Style	Effect
`standard`	Default — no system prompt modification
`explanatory`	Detailed step-by-step explanations with alternatives
`learning`	Teacher mode — first principles, analogies, related topics

bash
/style explanatory
/style learning
/style standard

Permission mode

Control how tool calls are approved with /permission or Shift+Tab:

Mode	Behavior
`auto`	Auto-approve safe tools
`ask`	Prompt for each tool call
`deny`	Deny all tool calls

bash
/permission auto
/permission ask

Shift+Tab cycles through modes: auto → ask → deny → auto.

Fast mode

Toggle minimal thinking with /fast:

bash
/fast                    # Toggle fast mode

When enabled, reduces thinking level and sets output style to standard for faster responses. Disabling restores previous thinking level and style.

Troubleshooting

No output after sending a message:

Run /status in the TUI to confirm the Gateway is connected and idle/busy.
Check the Gateway logs: mayros logs --follow.
Confirm the agent can run: mayros status and mayros models status.
If you expect messages in a chat channel, enable delivery (/deliver on or --deliver).
--history-limit <n>: History entries to load (default 200)

Connection troubleshooting

disconnected: ensure the Gateway is running and your --url/--token/--password are correct.
No agents in picker: check mayros agents list and your routing config.
Empty session picker: you might be in global scope or have no sessions yet.