Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Terminal setup, colours and screen readers

This page covers the terminal side of the terminal UI: getting a newline key to work, tmux and macOS settings, hyperlinks, colours and themes, the clipboard, notifications for pending prompts, and screen-reader mode. Fontaine has no /terminal-setup command: it never edits another program’s configuration file, so the settings below are yours to make.

New lines in the message box

Enter sends. These insert a newline instead:

KeyWorks in
Alt+EnterEvery terminal where Alt (Option on macOS) is sent as Meta; see Option as Meta.
Ctrl+JEvery terminal.
\ then EnterEvery terminal. The backslash is removed and the line continues.
Shift+EnterTerminals that report the Shift modifier on Enter.

Fontaine does not turn on the kitty keyboard protocol, so Shift+Enter only works where the terminal already reports it. In a terminal that cannot, bind Shift+Enter to send the Alt+Enter sequence, ESC followed by a carriage return. GNOME Terminal and other VTE-based terminals send the same bytes for Shift+Enter as for Enter and have no setting to change that; use Alt+Enter or Ctrl+J there.

VS Code and Cursor (integrated terminal). Add to keybindings.json:

{
  "key": "shift+enter",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b\r" },
  "when": "terminalFocus"
}

Alacritty (alacritty.toml):

[[keyboard.bindings]]
key = "Return"
mods = "Shift"
chars = "\u001b\r"

WezTerm (wezterm.lua):

config.keys = {
  { key = 'Enter', mods = 'SHIFT', action = wezterm.action.SendString '\x1b\r' },
}

Zed (keymap.json):

[
  {
    "context": "Terminal",
    "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] }
  }
]

tmux

tmux swallows modifiers on keys such as Shift+Enter unless extended keys are on. Add to ~/.tmux.conf:

set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

and restart the tmux server. Alt+Enter, Ctrl+J, \ then Enter and Ctrl/Alt with the arrow keys need no setting.

/copy sends the reply with an OSC 52 escape. tmux forwards it to the outer terminal under its default set-clipboard external; if you changed that to off, set it back:

set -g set-clipboard external

The outer terminal must itself accept OSC 52 clipboard writes.

Clickable hyperlinks need tmux 3.4 or later and a terminal that supports them; tell tmux so:

set -as terminal-features ',*:hyperlinks'

The osc9 and osc777 notifications are dropped by tmux unless it passes them through; set set -g allow-passthrough on. The default bell needs no setting beyond monitor-bell on. See the commands table for /copy.

Notifications

When a prompt that waits for your answer opens (an approval, a question from the model, an MCP server or skill trust prompt, the guardian-unavailable prompt or the /guardian-disable confirmation), Fontaine tells the terminal once, so you find out after switching windows. (A remote control ticket dialog is not one of these: it is a dialog you open yourself.) This includes approvals raised by background agents. [tui] notify in your user settings picks how:

ValueWhat is sent
bell (default)A bell (BEL). Most terminals flag the window or tab; in tmux set monitor-bell on.
osc9An OSC 9 desktop notification (iTerm2, Ghostty, WezTerm, Windows Terminal and others).
osc777An OSC 777 desktop notification (VTE-based terminals, Konsole, Ghostty, foot and others).
offNothing.
[tui]
notify = "osc9"

The text is fixed (Fontaine needs your approval, Fontaine has a question, …); nothing from the model or a tool reaches the escape sequence. A terminal that does not know the sequence ignores it, so try osc9 and osc777 in turn. The signal is sent once when the prompt opens, not when a reply finishes, and a prompt that was already signalled does not signal again when a panel such as /agents closes over it. Screen-reader mode ignores notify and keeps its own bell.

Word movement and deletion

Most Unix terminals send Ctrl-Backspace as Ctrl-H, which Fontaine treats as Backspace, so there it deletes one character. Use Alt-Backspace or Ctrl-W to delete a word; Alt needs Option as Meta on macOS.

Option as Meta on macOS

Alt+Enter, Alt-B, Alt-F and Alt-D arrive as ESC plus the key only when the terminal sends Option as Meta:

  • Terminal.app: Settings, Profiles, Keyboard, tick “Use Option as Meta key”.
  • iTerm2: Settings, Profiles, Keys, General, set “Left Option key” (and “Right Option key” if you use it) to “Esc+”.
  • VS Code and Cursor: set "terminal.integrated.macOptionIsMeta": true in the settings.

URLs, markdown links, owner/repo#N, #N (when the origin remote is on github.com) and file paths inside the project (dir/file, or name.ext:line) that exist and are neither executable nor launchable (scripts and .desktop files stay plain text) are sent as OSC 8 hyperlinks, so Ctrl-click or Cmd-click opens them in terminals that support it. The text shown is unchanged; a terminal without OSC 8 support ignores the extra bytes and shows the same text. A file link carries the machine’s hostname, as the OSC 8 specification asks, so a click over SSH does not open a same-named local file. See markdown in replies for what is linked.

Fontaine decides from the environment, in this order:

  1. FORCE_HYPERLINK=1 (any non-empty value but 0) turns links on, and FORCE_HYPERLINK=0 off.
  2. Inside tmux they are on. tmux 3.4 and later pass them to an outer terminal that has the hyperlinks feature (see tmux) and drop them otherwise.
  3. On Windows they are on in Windows Terminal (WT_SESSION) and in terminals that set TERM_PROGRAM, and off in the legacy console.
  4. They are off when TERM is unset, dumb, linux, or starts with screen (GNU screen).
  5. Otherwise they are on.

Screen-reader mode and headless runs never send them. There is no setting for it beyond FORCE_HYPERLINK.

Colours

Every colour in the interface comes from a theme. Six are built in:

ThemeFor
dark-ansi (default)A dark background, using the terminal’s own 16 colours.
light-ansiA light background, using the terminal’s own 16 colours.
darkA dark background, with fixed RGB colours.
lightA light background, with fixed RGB colours.
dark-daltonizedA dark background, with blue and orange in place of green and red.
light-daltonizedA light background, with blue and orange in place of green and red.

The -ansi themes follow whatever palette the terminal is set to and need no truecolor support. The others use fixed RGB values, which a terminal without truecolor approximates badly or not at all. The daltonized themes show a finished tool call in blue and a failed or denied one in orange, which readers with red-green colour blindness can tell apart. URLs and link text use an underlined blue in every theme, whether or not hyperlinks are on.

Choose one with /theme <name>, which applies at once and saves [tui] theme to your user settings file, or by writing the key yourself:

[tui]
theme = "light-daltonized"

/theme with no name lists the themes and marks the current one. Lines already written to the terminal’s scrollback keep the colours they were written in; a new theme applies to new lines and to the live area. [tui] is read from your user file and --settings only. There are no custom theme files and no automatic light or dark detection.

Fontaine also uses bold, dim and reversed text, for example to mark the selected row. When the NO_COLOR environment variable is set, colour is dropped, and the terminal library may drop that emphasis with it, so a selected row can lose its highlight. Most selected rows also carry a > marker, which stays.

ASCII glyphs

Notices start with · and warnings with ⚠. Where the terminal or its font cannot draw them, set FONTAINE_ASCII_GLYPHS=1 and they start with - and * instead. Any value except empty or 0 turns it on; it is read once at startup, and there is no settings key. The working spinner’s glyph becomes .oO0Oo.

Screen-reader mode

Screen-reader mode replaces the live area with plain, labelled lines appended in order, which a screen reader can follow. Turn it on with any of:

  1. --ax-screen-reader.
  2. FONTAINE_AX_SCREEN_READER=1 in the environment. FONTAINE_AX_SCREEN_READER=0 keeps it off even when the setting is true. Any other value is ignored, with a warning at startup.
  3. screen_reader = true under [tui] in your user settings file:
[tui]
screen_reader = true

The first line printed is [Screen Reader Mode: on via flag] (or env, or settings). A headless -p run ignores the mode. Keys do not change: Enter sends, and the dialogs keep their letter keys and arrows.

What is printed:

LineMeaning
you: ...A message you sent.
assistant: ...The model’s reply, printed a line at a time as it streams. The label appears once.
thinking: ...The model’s reasoning, once it has settled (it is not streamed). Long reasoning is cut to its first five lines, then expand: /expand thinking; that command prints all of it. A … clipped: only the start and end of the reasoning are kept line marks reasoning too large to keep whole. [tui] show_reasoning = false leaves it out.
tool: <tool> <summary> — doneA tool call that finished; — interrupted for one that did not. Its last ten output lines follow as plain lines, after … N earlier lines. expand: /expand N ends the card when the output was cut, the call spans several lines, or an edit, write or notebook_edit has a diff on a call that did not fail; a … clipped: only the start and end of the output are kept line marks output too large to keep whole. /expand N prints the card whole: a tool: <tool> — done line, the call’s lines, a diff header (path, added and removed counts) with + and - lines and no line numbers, then all the kept output.
tool error: <tool> <summary> — failed: ...A tool call that failed, or — denied: ... for one that was refused. A failed call’s output follows like a finished one’s.
error: ..., notice: ... and warning: ...Errors, notices and warnings. A warning’s advice follows on its own hint: ... line.
shell: <command>A ! command you ran, followed by its output.
no transcriptPrinted by Ctrl-O or /transcript when no entry has settled yet. Otherwise those print every settled entry once: calls and reasoning in the whole form /expand prints, the rest as above. No view opens.
Permission Required:An approval prompt opened. Its question, the call (for an edit, write or notebook_edit, its diff as plain text: line numbers, then + or - and the line), the choices and the rule the lasting answers would add follow.
<name>:Another dialog opened, for example model:, providers:, denied: or MCP server:.
remote:The remote control ticket dialog. The ticket is printed once, like any dialog, outside the transcript model; a line-oriented terminal cannot erase it, so your terminal’s scrollback keeps that one print until you clear it. The dialog never prints the QR code here, only the text ticket (fontaine-attach1…, which fontaine attach reads like the fontaine://pair/… link the code carries). In the graphical renderer dismissing the dialog, or a device presenting the ticket, removes it from the screen.
selected: ...The highlighted row of the open dialog.
viewing agent-3 (worker)You showed a subagent’s transcript. Its entries not printed before follow, and back to the main conversation and the main chat’s entries not printed before follow when you return. The terminal is not erased, so nothing is printed twice.
[manual mode on]The mode changed: [manual mode on], [accept edits on], [auto mode on], [AFK mode on] or [dontAsk mode on], however it changed.

A dialog is printed in full when it opens and afterwards only the lines that changed: moving the selection prints the newly selected row as selected: ..., and scrolling a long list prints the row that came into view. In the model picker each model row names its account (beta/llama3). While you type a reason for denying a call, a field of the provider dialog (including the startup setup dialog) or the model picker’s filter, each character you type is echoed as you type it and the prompt is not printed again. An API key is echoed as • bullets.

What you type is echoed after a > prompt, one character at a time. Editing anywhere except the end of the line prints the whole input again on a fresh line. When output arrives while you are typing, it is printed on the lines above and your input is echoed again below it, so the cursor always ends on the input line.

A bell (BEL) sounds when a reply finishes and when a prompt that needs an answer opens: an approval, a question, an MCP server or skill trust prompt, the auto-mode setup review, the guardian confirmation or the unavailable-guardian prompt. [tui] notify does not apply here.

Known limitations:

  • There is no status bar, so no working indicator and no running-agent count, and no agent list: /agents (or /tasks) opens the agents panel, and Enter on a subagent there is how you show its transcript. /status reports the mode and the model.
  • Messages queued while a turn runs are not announced; each is heard as you: ... when it is sent.
  • A running tool call is not announced until it ends. The absent bell tells you the turn is still going.
  • Terminal resizes are ignored, and cursor movement inside the input is not announced.
  • Dialogs are not numbered lists; use their letter keys and arrows.