TUI

Quick start

Gateway mode

1. Start the Gateway.

OmeniaClaw gateway

2. Open the TUI.

OmeniaClaw tui

3. Type a message and press Enter.

Remote Gateway:

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

Use --password if your Gateway uses password auth.

Local mode

Run the TUI without a Gateway:

OmeniaClaw chat# orOmeniaClaw tui --local

Notes:

• OmeniaClaw chat and OmeniaClaw terminal are aliases for OmeniaClaw tui --local.
• --local cannot be combined with --url, --token, or --password.
• Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
• After a config file has authored settings, OmeniaClaw and OmeniaClaw crestodian also use this TUI shell, with Crestodian as the local setup and repair chat backend.

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: agent + session + model + goal state + think/fast/verbose/trace/reasoning + token counts + deliver. When tui.footer.showRemoteHost is enabled, remote Gateway connections also show the connection host.
• 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.

• To show the Gateway host for non-local URL-backed connections, opt in with:

  OmeniaClaw config set tui.footer.showRemoteHost true

  Loopback and embedded local connections never show a host label.

• If the session has a goal, the footer shows its compact state such as Pursuing goal, Goal paused (/goal resume), or Goal achieved.

• When started without --session, gateway-mode TUI resumes the last selected session for the same gateway, agent, and session scope if that session still exists. Passing --session, /session, /new, or /reset remains explicit.

Sending + delivery

• Messages are sent to the Gateway; delivery to providers is off by default.
• The TUI is an internal source surface like WebChat, not a generic outbound channel. Harnesses that require tools.message for visible replies can satisfy the active TUI turn with a targetless message.send; explicit provider delivery still uses normal configured channels and never falls back to lastChannel.
• Turn delivery on:
  • /deliver on
  • or the Settings panel
  • or start with OmeniaClaw tui --deliver

Pickers + overlays

• Model picker: list available models and set the session override.
• Agent picker: choose a different agent.
• Session picker: shows up to 50 sessions for the current agent updated in the last 7 days. Use /session <key> to jump to an older known session.
• 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>
• /fast <status|on|off>
• /verbose <on|full|off>
• /trace <on|off>
• /reasoning <on|off|stream>
• /usage <off|tokens|full>
• /goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear
• /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

Local mode only:

• /auth [provider] opens the provider auth/login flow inside the TUI.

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).
• Local shell commands receive OmeniaClaw_SHELL=tui-local in their environment.
• A lone ! is sent as a normal message; leading spaces do not trigger local exec.

Repair configs from the local TUI

Use local mode when the current config already validates and you want the embedded agent to inspect it on the same machine, compare it against the docs, and help repair drift without depending on a running Gateway.

If OmeniaClaw config validate is already failing, start with OmeniaClaw configure or OmeniaClaw doctor --fix first. OmeniaClaw chat does not bypass the invalid- config guard.

Typical loop:

1. Start local mode:

OmeniaClaw chat

2. Ask the agent what you want checked, for example:

Compare my gateway auth config with the docs and suggest the smallest fix.

3. Use local shell commands for exact evidence and validation:

!OmeniaClaw config file!OmeniaClaw docs gateway auth token secretref!OmeniaClaw config validate!OmeniaClaw doctor

4. Apply narrow changes with OmeniaClaw config set or OmeniaClaw configure, then rerun !OmeniaClaw config validate.
5. If Doctor recommends an automatic migration or repair, review it and run !OmeniaClaw doctor --fix.

Tips:

• Prefer OmeniaClaw config set or OmeniaClaw configure over hand-editing OmeniaClaw.json.
• OmeniaClaw docs "<query>" searches the live docs index from the same machine.
• OmeniaClaw config validate --json is useful when you want structured schema and SecretRef/resolvability errors.

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.

Terminal colors

• The TUI keeps assistant body text in your terminal's default foreground so dark and light terminals both stay readable.
• If your terminal uses a light background and auto-detection is wrong, set OmeniaClaw_THEME=light before launching OmeniaClaw tui.
• To force the original dark palette instead, set OmeniaClaw_THEME=dark.

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

• --local: Run against the local embedded agent runtime
• --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
• --message <text>: Send an initial message after connecting
• --timeout-ms <ms>: Agent timeout in ms (defaults to agents.defaults.timeoutSeconds)
• --history-limit <n>: History entries to load (default 200)

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: OmeniaClaw logs --follow.
• Confirm the agent can run: OmeniaClaw status and OmeniaClaw models status.
• If you expect messages in a chat channel, enable delivery (/deliver on or --deliver).

Connection troubleshooting

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

Related

• Control UI — web-based control interface
• Config — inspect, validate, and edit OmeniaClaw.json
• Doctor — guided repair and migration checks
• CLI Reference — full CLI command reference