grok-build-upstream-mirror/crates/codegen/xai-grok-pager/docs/user-guide/21-terminal-support.md

Terminal Support and Troubleshooting

Grok Build runs as a full-screen TUI. It relies on terminal support for color, clipboard, keyboard input, mouse input, and full-screen display. Terminals, multiplexers, containers, and SSH sessions can handle these features differently.

Diagnose and Fix Terminal Problems

Run /doctor in Grok to check the current session and see available fixes. If Grok cannot start, run grok doctor in your shell. Use grok doctor --json for a machine-readable report.

Doctor checks the terminal, multiplexer, color support, keyboard and newline behavior, clipboard routes, and microphone availability when audio capture is included. The in-app command can also check live session details such as notification focus tracking and sandbox profile conflicts.

A report can contain issues or recommendations and still exit successfully. grok doctor --json reports the same color capability when piped. Microphone checks do not start recording, so Doctor cannot detect macOS permission failures that appear only as silence during capture.

/terminal-setup, /terminal-check, and /terminal-info remain aliases for /doctor.

When Doctor finds an explicit unhealthy tmux setting, /doctor fix lists the available automatic fixes. Apply one named fix at a time, for example /doctor fix tmux-clipboard or grok doctor fix dcs-passthrough --yes. Doctor can persist these four tmux options:

• terminal.tmux-clipboard — set -g set-clipboard on
• terminal.dcs-passthrough — set -wg allow-passthrough on
• terminal.tmux-extended-keys — set -g extended-keys on
• terminal.tmux-truecolor — set -as terminal-features ",*:RGB"

A tmux fix edits only the persistent config on the computer hosting the affected tmux server, including remote sessions. Plain tmux uses the real $HOME/.tmux.conf; Byobu-tmux uses its effective BYOBU_CONFIG_DIR and refuses to guess if that directory is unavailable or unsafe. Grok preserves the file's line endings and mode, makes a backup when changing an existing file, and refuses conflicting or ambiguous direct assignments.

Grok deliberately does not run tmux source-file or change the live tmux server. Reload with the exact command shown after apply, or detach and reattach, then run /doctor again. Until reload, the live finding is expected to remain. The conservative config scan checks direct global assignments only; review sourced files, conditionals, plugins, and generated tmux setup yourself.

---

Detected Terminals

Grok detects these terminal emulators from environment variables:

• Apple Terminal
• Ghostty
• iTerm2
• Warp
• WezTerm
• Kitty
• Alacritty
• Rio
• foot (Wayland-native, Linux)
• VS Code, Cursor, Windsurf, and Zed integrated terminals
• JetBrains IDE terminals
• Grok Desktop
• VTE-based terminals such as GNOME Terminal, GNOME Console, and Tilix
• Windows Terminal

Detection has these limitations:

• Inside tmux, variables that identify the outer terminal may not reach Grok.
• Over SSH, many terminal variables are not forwarded.
• tmux's global environment reflects the first client attached to the server, not necessarily the current terminal.

---

Common Problems and Fixes

Colors look wrong or lack truecolor

Run /doctor. A fully supported setup shows color truecolor and themes all. If it does not, Doctor shows the detected limitation and the relevant fix.

Inside tmux there are two separate questions: what color Grok emits, and what color survives the multiplexer. The color line answers the first. For the second, when the attached client is not marked RGB, tmux rewrites every 24-bit color to the nearest color the outer terminal's terminfo advertises, which can be as few as eight. Themes then look washed out even though color reads truecolor. Doctor reports this as terminal.tmux-truecolor. Reload your tmux config and then detach and reattach: the server reads the new option only on reload, and a client fixes its color depth only at attach, so neither step alone changes anything.

Clipboard problems

Grok writes through up to three routes, shown in /doctor under Clipboard:

• native — the local operating-system clipboard.
• tmux — the tmux paste buffer when Grok runs inside tmux.
• OSC 52 — an escape sequence that can cross tmux, containers, or SSH.

Wayland

Modern Wayland compositors can update the clipboard without keeping the terminal focused. Older compositors may require Grok to remain focused until the copy message appears. Grok shows a startup warning when this applies; run /doctor for the detected status and steps.

GROK_CLIPBOARD_NO_DATA_CONTROL=1 is an advanced fallback that disables the data-control route. Copies then use command-line clipboard tools.

OSC 52 kill switch

Grok emits OSC 52 on Linux and across tmux, SSH, or displayless containers when that route is enabled. A terminal that does not implement OSC 52 may display the encoded payload as text. Set GROK_CLIPBOARD_NO_OSC52=1 before starting Grok to disable that route. /doctor then shows osc 52 off; native and tmux routes are unchanged.

Linux X11 selections

X11 PRIMARY and CLIPBOARD are separate:

• An unmodified middle click reads PRIMARY only when DISPLAY is set. Under XWayland, xclip or xsel must be on PATH.
• Ctrl+V reads CLIPBOARD and never falls back to PRIMARY.
• Shift+Insert remains the terminal's selected-text paste.

SSH and selected text

A remote Grok process normally cannot read the local terminal's selection. Use terminal-native Shift+Insert, or hold Shift while middle-clicking when the terminal uses that gesture to bypass mouse reporting.

When Grok cannot identify the outer terminal over SSH, it predicts that OSC 52 will be sent but marks the route as not verified. The copy toast then names the backup file so you can retrieve the text. Run /doctor for other copy options.

Apple Terminal over SSH

Apple Terminal does not support OSC 52, so a remote copy cannot reach the local clipboard. Each copy is still saved to a backup file (~/.grok/last-copy.txt by default; override with GROK_COPY_FILE); the toast names that path when delivery is unverified or the clipboard is unreachable. You can also use /copy <file> or /minimal.

For direct clipboard forwarding, run the SSH command from the local computer through grok wrap, for example grok wrap ssh user@host. The same command can wrap container and pod shells. It also restores terminal modes after a dropped connection.

When an SSH session is not using grok wrap, Grok shows the one-time tip “Run /doctor for details and fixes.” The tip stops appearing after the session is launched through wrap. Turn it off with /settings → Show contextual hints → SSH wrap, or set ssh_wrap = false under [ui.contextual_hints] in $GROK_HOME/config.toml. This setting does not hide the Doctor recommendation.

For repeated SSH use, Doctor offers grok doctor fix ssh-wrap. It also shows the one-off command, the file that would change, and the cases where the alias should be bypassed. The ID terminal.ssh-wrap remains accepted and appears in JSON.

Warning

: grok wrap is experimental and may not work in every setup.

iTerm2

iTerm2 can require permission for OSC 52 clipboard access. Run /doctor; the terminal.iterm2-clipboard-permission recommendation shows the setting to check.

Fullscreen or alternate screen does not activate

Zellij and tmux control mode can limit the alternate screen. Grok normally uses inline mode in those environments. Run /doctor to see the detected condition. You can configure [terminal] alt_screen in ~/.grok/pager.toml, or run grok --no-alt-screen to confirm inline mode works.

Zellij keybindings interfere with Grok

Zellij can intercept Ctrl/Alt keys before they reach Grok. On Zellij 0.41 or later, use the Unlock-First (non-colliding) preset:

1. Press Ctrl+o, then c.
2. Open Change Mode Behavior.
3. Select Unlock-First (non-colliding).
4. Press Enter to apply it.

Press Ctrl+g when you need Zellij's own pane or session controls. In minimal mode, if Ctrl+G still does not reach Grok, open the command palette and select Edit Prompt in External Editor. This preserves the current draft; typing /edit-prompt starts an empty editor draft because the command itself occupies the composer.

Ctrl+Enter does not interject in WezTerm

WezTerm ships with the Kitty keyboard protocol disabled. Run /doctor in Grok. The terminal.wezterm-kitty finding shows the setting and restart step. Over SSH, Doctor shows only the workaround that can work in the current session. Apple Terminal uses Ctrl+O for interjection because it cannot distinguish the modified Enter chord.

Shift+Enter does not insert a newline in VS Code

VS Code, Cursor, Windsurf, and Zed terminals use xterm.js, which only partially implements the Kitty keyboard protocol and mis-encodes some shifted printable keys. Grok therefore does not negotiate the protocol there, and Shift+Enter can arrive as the same CR as Enter. This also affects VS Code reached over SSH when TERM_PROGRAM is not forwarded. Use Alt+Enter to insert a newline; /doctor reports terminal.newline-fallback with the detected explanation and workaround.

Mouse scrolling stops working

If Grok stops receiving mouse input, re-enable mouse reporting in the terminal:

• Apple Terminal: View → Allow Mouse Reporting (Cmd+R).
• iTerm2: Settings → Profiles → Terminal → Enable mouse reporting.

Voice dictation records nothing

After about 10 seconds without a transcript, Grok stops capture and shows “No speech was detected. Voice stopped.” with microphone fix steps. On macOS, a denied microphone grant can look the same as silence because permission belongs to the terminal hosting Grok. Open System Settings → Privacy & Security → Microphone, enable the terminal, and restart it. If access is already on, check the input device and level under System Settings → Sound → Input and try again.

Run grok doctor, or run /doctor while voice mode is on. The Voice section shows the microphone Grok would use. If no input device is available, Doctor shows voice.no-input-device and the next steps. Doctor cannot detect denied macOS microphone access passively when macOS supplies silence.

On macOS, each dictation uses a short-lived capture helper process so the audio stack's memory is released when capture ends. If the helper itself may be the problem, set GROK_VOICE_CAPTURE=inprocess to use the in-process fallback for comparison.

Byobu with GNU screen

Byobu on GNU screen has limited support. /doctor reports terminal.byobu-screen and explains how to switch to Byobu's tmux backend.

---

Still Stuck?

Run /feedback to report it.