TUI settings

Customize input layout, mouse interaction, keybindings, status placement, and terminal activity reports.

Open /settings and choose tui settings to control the main input chrome, mouse interaction, and where status information appears. Changes apply immediately and are saved in $ZOT_HOME/config.json.

SettingValues
click to position cursorOn or off, off by default. Click in the main input to move its cursor, or drag visible text to select it.
input styleplain keeps the default prompt line. lines draws separator lines above and below the input area. block renders a user-bubble-style input block.
status positionabove input or below input for model, usage, and working-directory information.
working spinner positionabove input or below input for the busy spinner shown while a turn is running.

Config keys

$ZOT_HOME/config.json
{
  "tui_click_to_position": true,
  "tui_input_style": "block",
  "tui_status_position": "below_input",
  "tui_working_position": "above_input"
}

tui_click_to_position accepts true or false. Input style accepts plain, lines, and block. Position fields accept above_input and below_input. Missing keys use the defaults: mouse interaction off, plain input, status above input, and spinner above input.

Mouse cursor and text selection

Enable **click to position cursor** under /settings > **tui settings**. A stationary left click in the main input moves the cursor, including wrapped lines and Unicode text. Click-drag selects visible chat or input text without moving the editor cursor. The selection stays highlighted after release and is not copied automatically.

ActionResult
[[ctrl+c]] with a selectionCopy explicitly without clearing the selection. Copying is silent unless an error can be detected.
[[esc]] with a selectionDismiss the selection without cancelling a running turn.
New click, typing, or scrollingClear the previous selection. The wheel browses zot's transcript.
Resize or disable the settingClear the selection. Disabling restores native terminal mouse behavior.

Display updates pause until the selection is dismissed so streaming cannot move selected text. The agent continues working, and the view catches up when the selection clears. Mouse interaction is ignored while a dialog owns input. Without a selection, ctrl+c and esc retain their usual behavior.

ctrl+shift+c and cmd+c can also copy if your terminal forwards the chord to zot. Terminal-native copy shortcuts that the emulator consumes cannot copy zot's highlighted selection. Use ctrl+c for explicit copying in zot.

Clipboard copy uses pbcopy on macOS, PowerShell on Windows, or wl-copy, xclip, or xsel on Linux. Over SSH, or when local copying fails, zot sends an OSC 52 clipboard request instead. Your terminal or multiplexer must allow it, and zot cannot verify that the request succeeded.

Requires a terminal with SGR button-motion reporting, such as Windows Terminal, iTerm2, Ghostty, or VS Code's integrated terminal on its supported operating systems. Selection covers only current visible text, excludes inline images, and copies displayed line breaks rather than reconstructing unwrapped source text. Dragging does not auto-scroll, and double-click word selection is not supported. This is zot-managed selection, not native terminal selection. Many terminals allow Shift-drag for native selection, including scrollback, but the bypass depends on the terminal.

Program status

In interactive mode, zot reports activity through the Program Status Protocol (OSC 7501). Supporting terminals and dashboards can show whether it is working, waiting for input, finished, or failed. This is separate from the visible status bar and is controlled by an environment variable, not a /settings toggle.

StateWhen and message
[[idle]]Startup or cancellation.
[[working]]A submitted agent run or shell command is in progress. The message is the explicit session name when available. Compaction uses "Compacting context".
[[blocked]]A tool confirmation, login dialog, extension panel, or model recovery dialog is waiting for input. Reports include a title and a permission, auth, or question category.
[[done]]Work finished successfully. The message is the explicit session name when available.
[[error]]Work failed without an automatic retry. The message is the first line of the error.

By default, zot queries the terminal for support and sends reports only after an acknowledgement. Automatic detection is skipped for non-TTY input/output and detected tmux or screen sessions. You can override detection for a single run:

sh
ZOT_PROGRAM_STATUS=1 zot   # force reporting without detection
ZOT_PROGRAM_STATUS=0 zot   # disable queries and reports

Forcing reports does not make a multiplexer forward them. Closing zot clears its reported status. Reporting is limited to the interactive client and work submitted there, not background agents or work submitted by other attached clients. Print, JSON, RPC, and bot modes do not emit these terminal sequences.

Messages use only explicit session names, dialog titles, and the first error line. Transcript text, tool previews, dialog bodies, and model output are not used as status messages. Prompt-derived session-picker titles are excluded. Names update after renaming through /sessions, and switching sessions clears the previous outcome. Legacy branch names are omitted because older rename records may contain generated prompt excerpts. Rename such a branch again to report an explicit name.

Message control characters become spaces. Text is limited to 2048 UTF-8 bytes without splitting characters, then base64-encoded for the wire format. Reports also identify the application as zot.

Base64 is not encryption. Names, dialog titles, and error lines may contain sensitive information. Use ZOT_PROGRAM_STATUS=0 if you do not want to share that metadata with the terminal.

Custom shortcuts

Bind key chords to slash commands or navigation actions with keymap in $ZOT_HOME/config.json. There is no /settings row for this yet. Edit the file and restart zot. Each key is a case-insensitive chord made of at least one modifier (ctrl, alt or option, shift, cmd or super) plus a single character or a named key (enter, tab, space, esc, backspace, delete, up, down, left, right, home, end, pageup, pagedown). A string value invokes a slash command. Built-in commands, extension commands, and /skill:<name> all work. An object value configures a navigation action.

$ZOT_HOME/config.json
{
  "keymap": {
    "alt+n": "/new",
    "ctrl+s": "/settings",
    "ctrl+g": "/git-tools:status",
    "alt+r": "/skill:code-review",
    "ctrl+n": { "action": "next", "context": "navigation" },
    "ctrl+p": { "action": "previous", "context": "navigation" }
  }
}

Slash-command shortcuts run in the main interactive input and use the same dispatch path as typing the command. They do not apply while a dialog, extension panel, or tool confirmation has focus. The example alt+n binding starts a fresh persisted session, but /new is unavailable when zot runs with --no-session.

Navigation objects support "next" and "previous" with the required context "navigation". They act like Down and Up in built-in lists and scrollable views, including model, session, settings, and confirmation dialogs, and in slash, file, and path suggestion popups. Navigation remains available while editing a list's filter. In confirmations, these actions move the selection without answering the request.

Text-only subviews and the main editor without a popup ignore navigation actions. They do not edit text, browse prompt history, or scroll the main chat. Extension panels control their own navigation and do not use these actions. There are no default ctrl+n or ctrl+p aliases. Add the entries above to enable them, or choose other modified chords. Existing arrow keys continue to work.

Existing string-valued keymaps remain compatible, and saving other settings preserves both command and action entries.

Unbindable chords, invalid command strings, unsupported actions or contexts, and the reserved ctrl+c, ctrl+d, and esc chords are skipped and reported above the transcript at startup (the notice clears with /clear). Unmodified keys such as enter or g cannot be rebound. Malformed binding values, wrong field types, or unknown object fields cause a config parse error. /help lists the active bindings under custom keys.

Without enhanced keyboard reporting (kitty keyboard protocol or xterm modifyOtherKeys), a terminal cannot distinguish ctrl+h, ctrl+i, and ctrl+m from Backspace, Tab, and Enter, and it does not report Shift on Ctrl+letter chords. zot therefore lets a ctrl+shift+<letter> binding also fire on plain ctrl+<letter> unless a separate ctrl+<letter> binding exists. Chords the terminal emulator or multiplexer consumes itself, such as a tmux prefix or cmd+k, never reach zot.