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 three 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`

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.

### 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.