TUI Guide
Last updated
Single bubbletea textarea (
internal/runtime/tui); slash commands open transient popups that close cleanly back to the prompt.Since v1.2.0 the TUI no longer runs agents itself: the daemon runs every request and the TUI is a client over the Unix socket ~/.config/agenvoy/daemon.sock (mode
0600, newline-delimited JSON frames). A run is bound to the connection that started it, so closing the TUI stops the run while its pending snapshot is kept. Confirmations and ask_user questions from that run go only to the TUI window that started it; a confirmation for a path outside $HOME, a sudo argv or sandbox: false asks for the system password in a TUI password field (a sensitive path inside $HOME only needs a plain confirmation) and the daemon verifies it (sudo -S -v). When the socket is down the status line shows Connecting and the TUI retries every 5 seconds; plain input, skills, /pending resume and scheduler dispatch wait until it reconnects, while local / commands keep working. The work directory is the TUI's own: set it with Shift+P. Removed in v1.3.0: the daemon no longer pushes a directory the agent switched to with cd, because the agent can no longer change it.Since v1.3.8, while the session has background legs running, the line above the input reads
N background task(s) running, followed by (esc to cancel) when no run is in progress; it refreshes every second. The v1.3.0 Waiting for background tasks (the reply continues here) line, and the follow-up mode behind it, were Removed in v1.3.8 because a run no longer stays pending for its background work (see Pending Tasks and Cancellation).Shortcuts
| Key | Action |
|---|---|
Enter | Send the current input. While a run is in flight only plain text is sent, as a steer message delivered to the running loop; / commands are neither listed nor sent until the run ends |
Alt+Enter | Insert a newline |
! prefix | Since v1.3.0, !<command> runs the rest of the line with $SHELL -c (/bin/sh when unset) in the TUI's work directory, from the TUI process itself rather than the sandbox, for at most 30 minutes; the input box turns red with a $ prompt while the line starts with !. The exit code and output (up to 32 KiB) print in the transcript, then go to the agent as a [Shell command] message asking it to report the result; that message is hidden from the chat history. Like any other message it needs a registered model and a connected daemon, and Esc / Ctrl+C stop the command. Since v1.3.2 a command containing the word sudo first checks for a valid sudo ticket; without one a System password: popup opens, the password is verified with sudo -S -v, and the command then runs reusing that ticket. A wrong password ends with [Denied] password: incorrect password; Esc closes the popup without running the command |
/ | Begin slash-command filter (popup picker — Up / Down to navigate, Tab / Enter to autocomplete into the textarea, Esc to dismiss) |
Up / Down | Walk input history when the cursor is on the first / last line (per-session .cmd_history file) |
Esc | Outside a popup, in this order (v1.2.0): dismiss the command picker, else close the notice box, else open the cancel popup while running — No, Yes (cancel), or Pause (keep pending). Cancel discards the pending task, pause stops the run and leaves it resumable through /pending; both also stop the task's background jobs. A run that has emitted nothing yet is cancelled straight away with no popup. Otherwise clear a non-empty input; with the input empty and no run, open the background-task menu (v1.3.8): No, each running leg and All (two or more), then a confirmation before the pick is cancelled |
Ctrl+C | While running, cancel the task outright (the user-cancel path — the pending task is discarded); otherwise print ctrl+c again to quit. A second Ctrl+C within 3 seconds quits the TUI |
Single-key toggles fire only when the input is empty, the command picker is closed and no run is active (
Shift+Tab only checks the last two):| Key | Action |
|---|---|
Shift+Tab | Toggle auto mode (safe ↔ auto) |
Shift+F | Toggle fast mode — the mode line shows [fast] while enabled |
Shift+G | Toggle CLAUDE.md / AGENTS.md injection (v1.2.0; off at start). When on and the work directory has one of those files, the mode line shows [CLAUDE.md] or [AGENTS.md] and the file is added to each turn's context |
Shift+U | Live provider usage / balance for every registered provider that reports one: codex, grok-oauth, copilot, deepseek, openrouter, claude-code (Ollama Cloud: Removed in v1.2.0); the result lands in the notice box. Since v1.1.3 a provider with several quota windows shows each one as 5h/week/total percentages, colored by its own level |
Shift+P | Open the Work directory popup (v1.3.0): an absolute path, ~/... or a path relative to the current directory; a path that does not exist is refused with [Not found] work directory, and the letter case of each segment is corrected to the one on disk |
Shift+W / Shift+S | Cycle the session model backward / forward through auto and the registered models (not the same as w / s inside /model, which reorder the fallback list) |
Shift+A / Shift+D | Cycle the session reasoning level down / up through auto, none, low, medium, high, xhigh, max — auto included since v1.1.0 |
Shell command mode (
Shift+T) was removed; since v1.3.0 the ! prefix runs a command directly instead. The Shift+M model list was removed; use /model, which lists the registered models.In list popups,
Enter confirms the highlighted entry, d deletes it and t sets its tier where the popup offers those actions. Text-input popups use Ctrl+S to confirm, Enter for a newline, and Esc to cancel.Since v1.3.3 confirmation, password and
ask_user popups ignore Esc: pick an option instead. A confirmation offers Yes, Yes don't ask again, Yes allow this turn, No skip this (with an optional reason for the agent), Abort keep for resume and Cancel delete task; password prompts (a path outside $HOME, sudo, sandbox: false) drop the two remember options while plain confirmations, including a sensitive path inside $HOME, keep them, and a wrong system password keeps the popup open until verification succeeds. A run_command / background_command confirmation shows the dispatcher model's explanation above a divider and the command. Open popups re-render when the terminal is resized, ask_user clips its question and detail to the window height so every option stays visible, and a task that ends while a popup is open no longer leaves the status stuck on running.The TUI auto-tails the active session's
action.log (foreign-process writes prefixed with ▌ in warn-purple). Single-session view only.Since v1.1.0 status messages (command results, errors,
Shift+U output) collect in a framed notice box above the input instead of scrolling into the transcript. Since v1.1.3 plain success confirmations — a saved role, a deleted key, a new session and the like — go to the debug log instead, so the box only holds what needs attention; since v1.3.0 empty-state and progress messages (no active session, nothing scheduled, compacting history... and the like) go there too, and since v1.3.2 so does the ⚠ restricted path approved notice. It keeps the last 32 lines and shows 4 at a time; Tab pages up when there are more, and Esc closes it.