Synced from monorepo
Changes: - Non-blocking coding-data sharing upsell banner - Consolidate remediation in Doctor - Auto mode defers fail-closed gate asks to the classifier - Coalesce marketplace list fetches - Allow removing a marketplace source by name - Contain hung git marketplace sources (timeouts, non-blocking refresh, unbrick modal) - Label failed workspace RPCs with error_kind - Drop redundant explicit tonic/prost deps from xai-grok-shell - Report real exit codes for completed background shells - Narrow the date-rollover reminder to date-bearing templates - Wire toolOverrides through the session and agent - Security: Bash(git:*) allowlist matches whole command chain by prefix - Split prompt-trigger telemetry and record classifier provenance - Raise connectors-manager timeout to 60s - Auto classifier honors recorded approvals for repeat actions - Apply doctor fixes in the TUI - Auto-mode classifier timeouts prompt instead of silently denying - Scope subagent completion drains to the owning session - Add the toolOverrides wire types - Set client_identifier=grok-agent-sdk - Accept both spellings of the workspace-teleport kill switch - Persist one-shot occurrence journal - Stop turns that poll the exact same tool call 16x in a row - Copy compaction checkpoint files when forking sessions - Auto-focus permission prompt from scrollback - Esc cancels the running turn in non-vim and minimal modes - List Ctrl+Z undo and redo in keyboard shortcuts - Out-of-process macOS mic capture - Show active auth mode on session-info - Install the npm binary under $GROK_HOME - Remove hover/click dead zones between dashboard items - Route startup warnings to doctor - Document [feedback.user] author identity config - Extend bang command timeout - Close combine-queued edit-hold race - Integrate relocation recovery - Expose privacy notice rollout flag - Break harness discovery ref cycle so connections can idle-evict - Shift/Alt+Enter inserts newline when editing a queued prompt - Gate project Claude permissions on folder trust - Echo response.create.event_id on response.created - Toast when session creation fails from disk full - Add shared test process lifecycle - Enable dynamic workflows by default - Add relocation transaction state machine - Add shared test sandbox - Surface auth failures on model-switch compact - Persist durable scheduler expiry - Confirm before removing extensions-modal items - Re-run compact and prompt after login when compact hit expired auth - Recap sends hosted tools under backend search
This commit is contained in:
grokkybara[bot]
parent
3af4d5d398
commit
a5727c5960
482 changed files with 37627 additions and 13402 deletions
|
|
@ -78,7 +78,7 @@ Once authenticated, Grok presents a full-screen TUI with two main areas:
|
|||
|
||||
Type a message and press `Enter` to send it. Grok reads files, runs commands, and edits code as needed. Each tool run streams into the scrollback in real time.
|
||||
|
||||
Press `Tab` to move focus between the prompt and the scrollback. While a turn is running, `Ctrl+C` cancels it (or clears a non-empty draft first); `Esc` is a no-op mid-turn. Idle, press `Esc` twice within 800ms to clear a non-empty prompt, or (with an empty prompt and conversation messages) to open rewind — see [Keyboard Shortcuts](03-keyboard-shortcuts.md#escape). With the scrollback focused, use the arrow keys to select entries and to collapse or expand them. To navigate with `j`/`k` and fold with `h`/`l` instead, enable Vim mode.
|
||||
Press `Tab` to move focus between the prompt and the scrollback. While a turn is running, `Esc` cancels it (the exception is fullscreen vim scrollback mode, where mid-turn `Esc` is a no-op; minimal mode cancels even with vim on); `Ctrl+C` cancels once the composer is empty — with a draft, the first press only clears it. Idle, press `Esc` twice within 800ms to clear a non-empty prompt, or (with an empty prompt and conversation messages) to open rewind — see [Keyboard Shortcuts](03-keyboard-shortcuts.md#escape). With the scrollback focused, use the arrow keys to select entries and to collapse or expand them. To navigate with `j`/`k` and fold with `h`/`l` instead, enable Vim mode.
|
||||
|
||||
### File References
|
||||
|
||||
|
|
|
|||
|
|
@ -95,21 +95,24 @@ Switch between the prompt input and scrollback pane.
|
|||
| `Tab` | | Prompt focused | Focus the scrollback (both simple and vim scrollback modes) |
|
||||
| `Enter` | | Prompt focused | Send the current prompt |
|
||||
|
||||
**Esc is not a focus key.** It follows clear / rewind semantics below (and swallows mid-turn), independent of `[ui].simple_mode` (prompt editor) and `[ui].vim_mode` (scrollback nav). Overlays, modals, slash/file dropdowns, voice, search, and selection still steal Esc first.
|
||||
**Esc is not a focus key.** It follows the cancel / clear / rewind semantics below. The mid-turn cancel is the only branch gated on `[ui].vim_mode` (scrollback nav); nothing depends on `[ui].simple_mode` (prompt editor). Overlays, modals, slash/file dropdowns, voice, search, and selection still steal Esc first.
|
||||
|
||||
## Escape
|
||||
|
||||
| State | Gesture | Effect |
|
||||
|--------|---------|--------|
|
||||
| Turn running | `Esc` | Swallowed no-op (does **not** cancel). Use `Ctrl+C` (or palette / other cancel entry points). |
|
||||
| Turn cancelling | `Esc` | Re-sends cancel (retry if the first ack was lost). `Ctrl+C` in this state escalates toward quit. |
|
||||
| Turn running, **minimal mode or vim scrollback mode off (the default)** | `Esc` | Cancel immediately (prompt or scrollback focused, even with a draft — the draft is **preserved**, unlike Ctrl+C's clear-first gesture). |
|
||||
| Turn running, **fullscreen vim mode** | `Esc` | Swallowed no-op (does **not** cancel). Use `Ctrl+C` (or palette / other cancel entry points). |
|
||||
| Turn cancelling | `Esc` | Re-sends cancel in **every** mode (retry if the first ack was lost). `Ctrl+C` in this state escalates toward quit. |
|
||||
| Idle + non-empty prompt (text or image chips), **prompt focused** | **2× `Esc` within 800ms** | Clear the prompt; non-empty text is saved to prompt history. First press shows “press again to clear”. |
|
||||
| Idle + empty prompt + conversation messages, **prompt or scrollback focused** | **2× `Esc` within 800ms** | Open the rewind picker (same as `/rewind`). First press is silent (no toast). |
|
||||
| Idle + empty + no messages, **or scrollback focused with a draft / moded (`!` `#` feedback) composer / pending needs-input overlay / open history search** | `Esc` | Swallowed no-op (does not focus scrollback). Clear is prompt-pane only; rewind requires an empty Normal-mode composer, no pending overlay, and no open history search — reading the scrollback never mutates your draft, your composer mode, a question awaiting an answer, or an in-progress search. |
|
||||
|
||||
**Steal-Esc (runs before mid-turn swallow / clear / rewind):** overlays, modals, slash/file/completion dropdowns, history search, scrollback search, text selection, link highlight, voice, and **Bash / Remember / Feedback mode exit** when the prompt is empty (Esc leaves `!` / `#` / feedback mode and returns to the normal prompt — even while a turn is running).
|
||||
**Post-cancel grace:** for about a second after an Esc-triggered cancel, the idle rewind arm stays suppressed — mashing Esc to stop a turn cannot silently open the rewind picker. Only the rewind arm is held; every other Esc behavior is unaffected.
|
||||
|
||||
**Ctrl+C vs Esc:** with a non-empty draft while a turn is running, Ctrl+C clears the draft and keeps the turn; a second Ctrl+C on an empty prompt cancels. Esc does not cancel a running turn (only retries while already cancelling). Idle non-empty Ctrl+C clears in one press; Esc requires two presses within 800ms.
|
||||
**Steal-Esc (runs before mid-turn cancel / swallow and clear / rewind):** overlays, modals, slash/file/completion dropdowns, history search, scrollback search, text selection, link highlight, voice, and **Bash / Remember / Feedback mode exit** when the prompt is empty (Esc leaves `!` / `#` / feedback mode and returns to the normal prompt — even while a turn is running).
|
||||
|
||||
**Ctrl+C vs Esc:** with a non-empty draft while a turn is running, Ctrl+C clears the draft and keeps the turn; a second Ctrl+C on an empty prompt cancels. Esc cancels immediately and preserves the draft (in fullscreen vim mode it does not cancel — it only retries while already cancelling). Idle non-empty Ctrl+C clears in one press; Esc requires two presses within 800ms.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ Show how the context window is being used: a category breakdown (system prompt,
|
|||
|
||||
### `/session-info`
|
||||
|
||||
Show session details — model, turn count, and context usage. Aliases: `/status`, `/info`.
|
||||
Show session details — auth method, model, turn count, and context usage. Aliases: `/status`, `/info`.
|
||||
|
||||
### `/fork`
|
||||
|
||||
|
|
@ -327,7 +327,7 @@ Open the MCP servers management modal.
|
|||
|
||||
### `/doctor`
|
||||
|
||||
Show the read-only terminal diagnostic report — color level, available themes, clipboard routes, live keyboard and screen evidence, and fixes for common issues. Aliases: `/terminal-setup`, `/terminal-check`, `/terminal-info`.
|
||||
Check the current session for terminal, clipboard, color, input, notification, and sandbox issues. Doctor shows what it found and how to resolve each issue. Run `/doctor fix` to list available automatic fixes; other findings include manual steps. `/terminal-setup`, `/terminal-check`, and `/terminal-info` remain aliases.
|
||||
|
||||
### `/release-notes`
|
||||
|
||||
|
|
|
|||
|
|
@ -124,8 +124,8 @@ You can also override this with `GROK_DEFAULT_SELECTED_PERMISSION`, which is han
|
|||
|
||||
| Value | Behavior |
|
||||
|-------|----------|
|
||||
| `false` (default) | Bare-letter and `Shift+letter` keys (`j`/`k`, `h`/`l`, `g`/`G`, `y`/`Y`, `o`/`O`, `r`, `x`, `e`/`E`, `H`/`L`, plus `i`) are suppressed in the scrollback: pressing one focuses the prompt and types the character. Arrows, `Tab`, `Space`, `PageUp`/`PageDown`, and every `Ctrl+letter` shortcut still navigate. `Esc` is **not** a scrollback key — it follows clear / rewind / mid-turn-swallow policy (see [Keyboard Shortcuts](03-keyboard-shortcuts.md#escape)). |
|
||||
| `true` | All vim-style scrollback bindings are active, exactly as listed in [Keyboard Shortcuts](03-keyboard-shortcuts.md). |
|
||||
| `false` (default) | Bare-letter and `Shift+letter` keys (`j`/`k`, `h`/`l`, `g`/`G`, `y`/`Y`, `o`/`O`, `r`, `x`, `e`/`E`, `H`/`L`, plus `i`) are suppressed in the scrollback: pressing one focuses the prompt and types the character. Arrows, `Tab`, `Space`, `PageUp`/`PageDown`, and every `Ctrl+letter` shortcut still navigate. `Esc` is **not** a scrollback key — it cancels a running turn, and while idle follows the clear / rewind policy (see [Keyboard Shortcuts](03-keyboard-shortcuts.md#escape)). |
|
||||
| `true` | All vim-style scrollback bindings are active, exactly as listed in [Keyboard Shortcuts](03-keyboard-shortcuts.md). Mid-turn `Esc` is swallowed in this mode (`Ctrl+C` cancels); minimal mode keeps Esc-cancel regardless. |
|
||||
|
||||
Toggle it at runtime with `/vim-mode`, or from `/settings` → **Vim scrollback navigation**. Grok writes the change to `[ui] vim_mode` immediately and applies it to every future pager session, including new agents and subagents in the same process. There's no per-session override — `config.toml` is the source of truth on next launch. `vim_mode` is independent of `simple_mode`.
|
||||
|
||||
|
|
@ -306,11 +306,11 @@ To pin the model a subagent uses, set its entry under `[subagents.models]`.
|
|||
|
||||
`/goal` has two drivers, chosen by the background-workflows setting. With workflows enabled, the host-owned workflow engine evaluates rounds and drives completion verification; with them disabled, `/goal` falls back to the legacy model-facing `update_goal` tool. Whether `/goal` is available at all is a separate switch (the goal feature setting).
|
||||
|
||||
Background workflows — the `workflow` tool, named `.grok/workflows/*.rhai` scripts, `/deep-research`, and `/workflow` launches — are **off by default**.
|
||||
Background workflows — the `workflow` tool, named `.grok/workflows/*.rhai` scripts, `/deep-research`, and `/workflow` launches — are **on by default**. Disable with config, env, or remote settings.
|
||||
|
||||
```toml
|
||||
[workflows]
|
||||
enabled = true # enable background workflows (or GROK_WORKFLOWS=1)
|
||||
enabled = false # disable background workflows (or GROK_WORKFLOWS=0)
|
||||
```
|
||||
|
||||
Project workflows are discovered from `<repo-root>/.grok/workflows/`; user workflows from `~/.grok/workflows/`. Discovery and invocation key off the script's `meta.name`, so keep each filename aligned with its `meta.name`. Built-ins win over project names, and project names win over user names, so keep names unique across scopes.
|
||||
|
|
@ -471,16 +471,7 @@ timeout_secs = 5
|
|||
|
||||
#### Troubleshooting
|
||||
|
||||
**Notifications not working in tmux:** tmux blocks escape sequences by default, so enable passthrough:
|
||||
|
||||
```bash
|
||||
# In ~/.tmux.conf
|
||||
set -g allow-passthrough on
|
||||
```
|
||||
|
||||
Restart tmux afterward. If passthrough isn't available (tmux < 3.3), set `method = "bel"`, which works without it.
|
||||
|
||||
**Focus tracking not working:** some terminals don't report focus events. If `condition = "unfocused"` never fires, try `condition = "always"`. Grok supports focus tracking in every detected terminal except Apple Terminal and unrecognized ones.
|
||||
Run `/doctor` in the affected session. It shows the detected notification and focus issues, the relevant configuration file, and the steps to resolve them. An explicit `method = "bel"` is treated as intentional. `method = "none"` turns off notification and focus findings.
|
||||
|
||||
**Sleep prevention not taking effect:** on macOS, sleep prevention uses `IOPMAssertionCreateWithName` via CoreFoundation; on Linux, `systemd-inhibit` (which must be on `$PATH`). Make sure the relevant tool is available. Prevention is only active during agent turns and releases automatically when the turn ends.
|
||||
|
||||
|
|
@ -694,7 +685,7 @@ The key ones. See the README for the complete list.
|
|||
|----------|-------------|
|
||||
| `GROK_MEMORY` | Enable (`1`) or disable (`0`) cross-session memory |
|
||||
| `GROK_SUBAGENTS` | Enable (`1`) or disable (`0`) subagents |
|
||||
| `GROK_WORKFLOWS` | Enable (`1`) or disable (`0`) background workflows and select the `/goal` driver (default off: legacy `update_goal`; on: host-owned workflow driver) |
|
||||
| `GROK_WORKFLOWS` | Enable (`1`) or disable (`0`) background workflows and select the `/goal` driver (default on: host-owned workflow driver; off: legacy `update_goal`) |
|
||||
| `GROK_WEB_FETCH` | Enable (`1`) or disable (`0`) the web_fetch tool |
|
||||
| `GROK_WEB_FETCH_ALLOW_LOCAL` | Allow `web_fetch` to explicit loopback hosts only (`localhost` / `127.0.0.0/8` / `::1`). Same as `[toolset.web_fetch] allow_local`. Default off; private/metadata stay blocked. |
|
||||
| `GROK_AGENT` | Custom agent definition path or name |
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ On startup, Grok detects your terminal's color capability level:
|
|||
|
||||
When you set `NO_COLOR`, Grok emits no color and renders in monochrome.
|
||||
|
||||
Run `/doctor` to see the detected level (`color` row) and which themes the picker offers on this terminal (`themes` row). When truecolor is missing, the issues section explains how to enable it (or that Terminal.app cannot).
|
||||
Run `/doctor` to see the detected color level and the themes available on this terminal. If truecolor is unavailable, Doctor shows the relevant setup steps or explains the terminal limitation.
|
||||
|
||||
### Automatic Quantization
|
||||
|
||||
|
|
|
|||
|
|
@ -185,7 +185,7 @@ From the modal you can:
|
|||
- Expand a server to view the tools it provides
|
||||
- Refresh the list with `r` after you edit `config.toml`
|
||||
- Authenticate an OAuth server with `i`
|
||||
- Add a server with `a`, or remove one with `x`
|
||||
- Add a server with `a`, or remove a local server with `x` (the modal asks for confirmation; press lowercase `y` to remove, or any other key to cancel)
|
||||
|
||||
### Tool Discovery
|
||||
|
||||
|
|
|
|||
|
|
@ -80,11 +80,13 @@ Use these keys in the Plugins tab:
|
|||
| `r` | Reload all plugins |
|
||||
| `a` | Add a plugin from `owner/repo`, a URL, or a local path |
|
||||
| `Space` | Enable or disable the selected plugin |
|
||||
| `x` | Uninstall the selected plugin |
|
||||
| `x` | Uninstall the selected plugin (asks for confirmation) |
|
||||
| `f` | Filter by status (all, enabled, or disabled) |
|
||||
| `Enter` | Expand or collapse plugin details |
|
||||
| `/` | Search plugins by name |
|
||||
|
||||
Uninstall asks for confirmation: press lowercase `y` to confirm, or any other key (including `Esc`) to cancel.
|
||||
|
||||
### Marketplace tab
|
||||
|
||||
Browse and install plugins from your configured marketplace sources.
|
||||
|
|
@ -94,9 +96,9 @@ Use these keys in the Marketplace tab:
|
|||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `i` | Install the selected plugin |
|
||||
| `d` | Uninstall the selected plugin |
|
||||
| `d` | Uninstall the selected plugin (asks for confirmation) |
|
||||
| `a` | Add a marketplace source |
|
||||
| `x` | Remove the selected source and its plugins |
|
||||
| `x` | Remove the selected source and all its plugins (asks for confirmation) |
|
||||
| `r` | Refresh marketplace sources |
|
||||
| `u` | Update the selected marketplace plugin |
|
||||
| `Enter` | Expand or collapse a source or plugin |
|
||||
|
|
@ -294,4 +296,4 @@ These keys work across every tab in the modal:
|
|||
| `/` | Search the current tab by name |
|
||||
| `Esc` | Clear the search, or close the modal |
|
||||
|
||||
Some actions, such as uninstalling a plugin, ask for confirmation. Press `y` to confirm or `Esc` to cancel.
|
||||
Destructive remove and uninstall actions in the modal ask for confirmation. Press lowercase `y` to confirm, or any other key (including `Esc`) to cancel.
|
||||
|
|
|
|||
|
|
@ -333,7 +333,7 @@ Press `Ctrl+L` on non–VS Code family terminals to open the Extensions modal (P
|
|||
|-----|--------|
|
||||
| `r` | Reload all hooks from disk |
|
||||
| `a` | Add a custom hook by path |
|
||||
| `x` | Remove the selected hook |
|
||||
| `x` | Remove the selected hook source (asks for confirmation; press lowercase `y` to confirm) |
|
||||
| `Space` | Enable or disable the selected hook |
|
||||
| `f` | Cycle the status filter (All / Enabled / Disabled) |
|
||||
|
||||
|
|
|
|||
|
|
@ -170,6 +170,7 @@ This shows:
|
|||
|
||||
- Session title (when set)
|
||||
- Shell version
|
||||
- Auth method (OAuth vs API key) and where to manage account and credits (https://grok.com/?_s=billing for OAuth, console.x.ai for API key; API-key sessions also suggest `grok login` for SuperGrok)
|
||||
- Session ID
|
||||
- Working directory
|
||||
- Model (with a model hash for coding models)
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ grok --sandbox project
|
|||
|
||||
A custom profile can't reuse a built-in name. `--sandbox devbox` always runs the built-in `devbox` profile, shadowing any `[profiles.devbox]` you define.
|
||||
|
||||
When the global and per-project files define the same custom profile name, the user-level definition takes precedence and the project definition is ignored. If those two definitions differ, Grok warns about the conflict at startup — on the welcome screen in the TUI, and on stderr for headless runs. Identical duplicate definitions do not produce a warning.
|
||||
If the user and project files define the same custom profile differently, Grok uses the user profile and shows a startup warning. Run `/doctor` to see both file locations and how to resolve the conflict. Identical definitions do not produce a warning.
|
||||
|
||||
### Custom Profile Fields
|
||||
|
||||
|
|
|
|||
|
|
@ -1,50 +1,27 @@
|
|||
# Terminal Support and Troubleshooting
|
||||
|
||||
Grok Build runs as a full-screen TUI. To draw the interface, it relies on terminal escape sequences for color, clipboard, mouse, and full-screen control. Some terminals, multiplexers, and SSH sessions handle these sequences differently.
|
||||
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.
|
||||
|
||||
## Quick Fixes
|
||||
## Diagnose and Fix Terminal Problems
|
||||
|
||||
### Truecolor / Washed-out or wrong colors
|
||||
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.
|
||||
|
||||
```bash
|
||||
# Add to ~/.zshrc or ~/.bashrc
|
||||
export COLORTERM=truecolor
|
||||
```
|
||||
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.
|
||||
|
||||
Inside tmux or over SSH, also add to your tmux config:
|
||||
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.
|
||||
|
||||
```tmux
|
||||
# ~/.tmux.conf or ~/.byobu/.tmux.conf
|
||||
set -g default-terminal "tmux-256color"
|
||||
set -as terminal-features ",*:RGB"
|
||||
```
|
||||
|
||||
### Recommended tmux settings (clipboard + passthrough)
|
||||
|
||||
```tmux
|
||||
set -g set-clipboard on
|
||||
set -g allow-passthrough on
|
||||
```
|
||||
|
||||
After editing, run:
|
||||
|
||||
```bash
|
||||
tmux source-file ~/.tmux.conf
|
||||
# or detach and reattach
|
||||
```
|
||||
|
||||
### Terminal diagnostics
|
||||
|
||||
Run a read-only report from your shell without starting the TUI:
|
||||
|
||||
```bash
|
||||
grok doctor
|
||||
grok doctor --json # machine-readable report
|
||||
```
|
||||
|
||||
The command reports the terminal, multiplexer, **color level**, **available themes**, the same compact **Clipboard** preflight status used by `/doctor`, and—when this build can capture audio—the **microphone** it would open. It also lists detected issues, recommendations, and probes that could not run. It exits successfully when it produces a report, even when the report contains issues or recommendations. Color detection uses stderr or the controlling terminal rather than stdout, so `grok doctor --json | jq` reports the same terminal capabilities as direct output. Passive mic lookup does not open a stream and cannot detect a denied macOS microphone grant.
|
||||
|
||||
Inside Grok, run the read-only `/doctor`. It uses the same diagnostic facts and clipboard policy, with runtime-only evidence such as the current screen mode, Kitty keyboard negotiation, and XTVERSION replies. When voice mode is on, it also shows the Voice section. Standalone doctor points to `/doctor` only for live-TUI evidence; skipped tmux and other external probes remain separate unavailable notes. When color is below truecolor, both reports explain how to unlock truecolor-only themes (TokyoNight, RosePineMoon, OscuraMidnight), or note that Terminal.app is inherently 256-color. The permanent aliases `/terminal-setup`, `/terminal-check`, and `/terminal-info` run the same slash command.
|
||||
`/terminal-setup`, `/terminal-check`, and `/terminal-info` remain aliases for
|
||||
`/doctor`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -52,7 +29,7 @@ Inside Grok, run the read-only `/doctor`. It uses the same diagnostic facts and
|
|||
|
||||
Grok detects these terminal emulators from environment variables:
|
||||
|
||||
- **Apple Terminal** (Terminal.app)
|
||||
- **Apple Terminal**
|
||||
- **Ghostty**
|
||||
- **iTerm2**
|
||||
- **Warp**
|
||||
|
|
@ -62,173 +39,178 @@ Grok detects these terminal emulators from environment variables:
|
|||
- **Rio**
|
||||
- **foot** (Wayland-native, Linux)
|
||||
- **VS Code**, **Cursor**, **Windsurf**, and **Zed** integrated terminals
|
||||
- **JetBrains** IDE terminals (IntelliJ, PhpStorm, and others)
|
||||
- **JetBrains** IDE terminals
|
||||
- **Grok Desktop**
|
||||
- **VTE**-based terminals (GNOME Terminal, GNOME Console, Tilix)
|
||||
- **VTE**-based terminals such as GNOME Terminal, GNOME Console, and Tilix
|
||||
- **Windows Terminal**
|
||||
|
||||
Detection has these limitations:
|
||||
|
||||
- Inside tmux, the variables Grok needs to identify the terminal don't reach the pager.
|
||||
- Over SSH, many terminal variables aren't forwarded.
|
||||
- tmux's global environment (`tmux -g`) reflects the first client that attached to the server, not your current session.
|
||||
- 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
|
||||
|
||||
### Problem: Colors look wrong or lack truecolor
|
||||
### Colors look wrong or lack truecolor
|
||||
|
||||
**Cause**: `COLORTERM` not set or tmux not configured for 24-bit RGB.
|
||||
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.
|
||||
|
||||
**Fix**: Apply the two settings above, then restart Grok.
|
||||
### Clipboard problems
|
||||
|
||||
**Verify**: Run `/doctor`. Expect `color truecolor` and `themes all`. If `color` is `256` or `basic`, the issues section has the unlock fix.
|
||||
Grok writes through up to three routes, shown in `/doctor` under **Clipboard**:
|
||||
|
||||
### Problem: Clipboard problems
|
||||
- **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.
|
||||
|
||||
Grok writes to the clipboard through up to three routes, shown in the **Clipboard** section of `/doctor`:
|
||||
#### Wayland
|
||||
|
||||
- **native** — Grok always writes to the native OS clipboard first.
|
||||
- **tmux buffer** — inside tmux, Grok also writes to the tmux paste buffer (`tmux load-buffer`).
|
||||
- **OSC 52** — Grok emits the OSC 52 escape sequence so the outer terminal updates its clipboard. Grok always emits OSC 52 inside tmux. Outside tmux, it emits OSC 52 on Linux, over SSH, or in a container without a display.
|
||||
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.
|
||||
|
||||
**Linux Wayland**: on compositors that support the data-control protocol (GNOME 48+, KDE, Sway, Hyprland — the **Clipboard** section shows `data-control on`; the line is omitted off Wayland) copies work even if the terminal loses focus mid-copy. On older compositors (GNOME 46/47), keep the terminal focused until the copy toast confirms, and install the `wl-clipboard` package (provides `wl-copy`) for the most reliable route — Grok shows a startup warning when this applies. If data-control misbehaves on your compositor, set `GROK_CLIPBOARD_NO_DATA_CONTROL=1` to stop Grok from speaking that protocol entirely — copies then go through the CLI tools (`wl-copy`/`xclip`).
|
||||
`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 every Linux copy (and over SSH/tmux/containers). Terminals that do not implement OSC 52 may paint the base64 payload as visible garbage (for example some VNC/X11 clients such as OpenText Exceed). Set `GROK_CLIPBOARD_NO_OSC52=1` before starting Grok to force the OSC 52 leg off; `/doctor` then shows `osc 52 off`. Native and tmux clipboard legs are unchanged.
|
||||
#### OSC 52 kill switch
|
||||
|
||||
**Linux X11 selections**: X11 **PRIMARY** and **CLIPBOARD** are separate. Selecting text usually fills PRIMARY; an explicit Copy action fills CLIPBOARD. In Grok:
|
||||
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.
|
||||
|
||||
- An unmodified middle click reads PRIMARY only when `DISPLAY` is non-empty. Pure X11 can fall back to the native arboard reader. XWayland must have `xclip` or `xsel` on `PATH`; Grok deliberately disables the arboard fallback there so it cannot substitute Wayland PRIMARY.
|
||||
- `Ctrl+V` reads CLIPBOARD only and never falls back to PRIMARY. To fill CLIPBOARD from a shell, run `printf %s "text" | xclip -selection clipboard`.
|
||||
- `Shift+Insert` remains the terminal-native selected-text paste. Native Wayland PRIMARY behavior is compositor/terminal-specific and is not inferred from `TERM` or an incoming mouse event.
|
||||
#### Linux X11 selections
|
||||
|
||||
**SSH and selected text**: a remote Grok process usually cannot read the local terminal's PRIMARY or CLIPBOARD selection. Use terminal-native `Shift+Insert`, or hold `Shift` while middle-clicking when your terminal uses that gesture to bypass mouse reporting. The terminal then sends the local selection through the PTY instead of asking the remote process to access it.
|
||||
X11 **PRIMARY** and **CLIPBOARD** are separate:
|
||||
|
||||
**Unknown terminals over SSH**: when Grok cannot identify the outer terminal, it sends the copy but reports delivery as unverified. If paste fails, reconnect with `grok wrap <ssh command>` or use `/minimal`.
|
||||
- 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.
|
||||
|
||||
**Known limitation — Apple Terminal + SSH**:
|
||||
Apple Terminal ignores OSC 52, so copying from a Grok session over SSH can't reach your local clipboard. Grok writes every in-app copy to a backup file (`~/.grok/last-copy.txt`, override with `GROK_COPY_FILE`) and the toast names the path — so you can `cat`/`scp` it. You can also target a file explicitly with `/copy out.txt` or `/copy 2 ~/reply.md`. For native drag-select copy (terminal selection → local clipboard), turn mouse capture off with `/toggle-mouse-reporting` (opt-in feature) or run `grok --minimal`.
|
||||
#### SSH and selected text
|
||||
|
||||
**Optional workaround for live clipboard**: Use `grok wrap ssh` instead of plain `ssh` (for example, `grok wrap ssh user@host`). It runs the command in a local PTY that intercepts OSC 52 sequences, including tmux-wrapped ones, and writes their contents to your local clipboard. The same command wraps anything else whose clipboard can't reach you — for example `grok wrap docker exec -it <container> bash` or `grok wrap kubectl exec -it <pod> -- bash`.
|
||||
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.
|
||||
|
||||
`grok wrap` also protects your local terminal from dirty disconnects: if the wrapped command dies while a remote TUI has mouse reporting, the alternate screen, or similar modes enabled (for example the SSH connection drops mid-session), wrap resets those modes on exit instead of leaving the terminal spraying mouse escape codes.
|
||||
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 message shows the
|
||||
actual result and backup file. Run `/doctor` for other copy options.
|
||||
|
||||
When Grok starts inside an SSH session that isn't already running under `grok wrap`, a one-time contextual tip above the prompt recommends `grok wrap ssh <host>` (it stops appearing on its own once you launch through wrap). To turn it off, set `ssh_wrap = false` under `[ui.contextual_hints]` in `~/.grok/config.toml`, or use `/settings` → **Show contextual hints** → **SSH wrap**.
|
||||
#### Apple Terminal over SSH
|
||||
|
||||
For repeated use, run `grok doctor fix ssh-wrap` on your **local machine**. Canonical `terminal.ssh-wrap` remains accepted and appears in JSON. After showing the exact change and asking for confirmation, it adds an interactive-shell alias to `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`. Automatic setup is unavailable on Windows. The safety scan refuses direct `ssh` alias/function declarations in that target file only; aliases from sourced files, plugins, or dynamic shell setup require manual review before confirming. Use `command ssh ...` to bypass the alias. For manually typed `ssh -f`, ControlPersist workflows, or OpenSSH's `~^Z` local suspend, use the bypass because wrapping is not fully transparent for those cases.
|
||||
Apple Terminal does not support OSC 52, so a remote copy cannot directly reach
|
||||
the local clipboard. Grok also saves each copy to the backup file named in the
|
||||
copy message (`~/.grok/last-copy.txt` by default; override with
|
||||
`GROK_COPY_FILE`). You can also use `/copy <file>` or `/minimal`.
|
||||
|
||||
> **Warning**: `grok wrap` is **experimental** and may misbehave in some setups.
|
||||
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.
|
||||
|
||||
**iTerm2 setting**:
|
||||
iTerm2 requires explicit permission for OSC 52:
|
||||
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.
|
||||
|
||||
1. iTerm2 → **Settings** → **General** → **Selection**
|
||||
2. Enable **"Applications in terminal may access clipboard"**
|
||||
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.
|
||||
|
||||
This setting is off by default for security reasons. Without it, OSC 52 writes from Grok (or any TUI) will be ignored.
|
||||
> **Warning**: `grok wrap` is experimental and may not work in every setup.
|
||||
|
||||
**Fix for other cases**:
|
||||
- `set -g set-clipboard on` in tmux config
|
||||
- For other terminals over SSH, switch to iTerm2, Ghostty, WezTerm, or Kitty for native OSC 52 support
|
||||
#### iTerm2
|
||||
|
||||
### Problem: Fullscreen / alternate screen not activating (inline mode)
|
||||
iTerm2 can require permission for OSC 52 clipboard access. Run `/doctor`; the
|
||||
`terminal.iterm2-clipboard-permission` recommendation shows the setting to
|
||||
check.
|
||||
|
||||
**Cause**: Zellij, tmux control mode (`tmux -CC`), or config set to `never`.
|
||||
### Fullscreen or alternate screen does not activate
|
||||
|
||||
**Fix**:
|
||||
- In Zellij or control mode, Grok intentionally runs inline (no alt screen).
|
||||
- Set `[terminal] alt_screen = "always"` in `~/.grok/pager.toml` to force fullscreen.
|
||||
- Use the CLI flag `--no-alt-screen` to disable alt-screen mode entirely (useful for debugging or when the alternate screen causes issues in your terminal).
|
||||
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.
|
||||
|
||||
### Problem: Zellij keybindings interfere with Grok (Ctrl+g, Ctrl+o, etc.)
|
||||
### Zellij keybindings interfere with Grok
|
||||
|
||||
Zellij intercepts many Ctrl/Alt key combinations before they reach full-screen TUIs like Grok.
|
||||
Zellij can intercept Ctrl/Alt keys before they reach Grok. On Zellij 0.41 or
|
||||
later, use the **Unlock-First (non-colliding)** preset:
|
||||
|
||||
**Best fix** (Zellij 0.41+): Switch to 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.
|
||||
|
||||
1. Press `Ctrl+o` → `c` (open Configuration)
|
||||
2. Go to **"Change Mode Behavior"**
|
||||
3. Select **"Unlock-First (non-colliding)"**
|
||||
4. Press `Enter` (or `Ctrl+a` to save permanently)
|
||||
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.
|
||||
|
||||
After this, Zellij starts **locked**. Most keys pass through to Grok. Press `Ctrl+g` to temporarily unlock Zellij when you need its pane/session management.
|
||||
### Ctrl+Enter does not interject in WezTerm
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Zellij recommends this approach for TUI users.
|
||||
### Shift+Enter does not insert a newline in VS Code
|
||||
|
||||
### Problem: `Ctrl+Enter` doesn't interject in WezTerm
|
||||
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.
|
||||
|
||||
**Cause**: WezTerm ships with the Kitty keyboard protocol disabled. Grok relies on it to tell `Ctrl+Enter` (interject) and `Shift+Enter` (send in multiline mode) apart from plain `Enter`. Most other terminals enable the protocol when Grok requests it.
|
||||
### Mouse scrolling stops working
|
||||
|
||||
For the same reason, in Apple Terminal, Grok binds `Ctrl+O` to interject.
|
||||
If Grok stops receiving mouse input, re-enable mouse reporting in the terminal:
|
||||
|
||||
**Fix**:
|
||||
- **Apple Terminal**: **View → Allow Mouse Reporting** (`Cmd+R`).
|
||||
- **iTerm2**: **Settings → Profiles → Terminal → Enable mouse reporting**.
|
||||
|
||||
Add this after `config = wezterm.config_builder()` in `~/.config/wezterm/wezterm.lua`:
|
||||
### Voice dictation records nothing
|
||||
|
||||
```lua
|
||||
config.enable_kitty_keyboard = true
|
||||
```
|
||||
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.
|
||||
|
||||
Reload (`Cmd+Shift+R` or restart WezTerm) and restart `grok`.
|
||||
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.
|
||||
|
||||
**Verify**: Run `/doctor` inside Grok. While a turn is active, you see the interject hint, and `Ctrl+Enter` interjects.
|
||||
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.
|
||||
|
||||
**Quick workaround** (no global change):
|
||||
### Byobu with GNU screen
|
||||
|
||||
```lua
|
||||
table.insert(config.keys, {
|
||||
key = "Enter",
|
||||
mods = "CTRL",
|
||||
action = wezterm.action.SendString("\x1b[13;5u"),
|
||||
})
|
||||
```
|
||||
|
||||
### Problem: `Shift+Enter` doesn't insert a newline in VS Code
|
||||
|
||||
**Cause**: VS Code's integrated terminal (and the Cursor / Windsurf / Zed
|
||||
forks) use xterm.js, which only partially implements the Kitty keyboard
|
||||
protocol — it mis-encodes shifted printable keys (`!@#$%^&*()` arrive as
|
||||
plain digits). Grok therefore never negotiates the protocol for these
|
||||
terminals. Without it, xterm.js sends a bare `CR` for `Shift+Enter`,
|
||||
byte-for-byte identical to plain `Enter`, so the chord can't be told apart
|
||||
and the prompt submits.
|
||||
|
||||
This also affects VS Code reached **over SSH** (e.g. into a devbox or
|
||||
container): `TERM_PROGRAM` isn't forwarded, so Grok sees an `Unknown`
|
||||
terminal and skips the protocol for the same reason.
|
||||
|
||||
**Fix**: Use **`Alt+Enter`** to insert a newline. xterm.js delivers it
|
||||
reliably as `ESC`+`CR` regardless of the keyboard protocol, and Grok's
|
||||
prompt hint bar advertises `Alt+Enter: newline` whenever it detects this
|
||||
situation. Run `/doctor` to confirm — the `newline` row shows
|
||||
`Alt+Enter` when `Shift+Enter` is unavailable.
|
||||
|
||||
### Problem: Mouse scrolling stops working (native scrollbar takes over)
|
||||
|
||||
If Grok's mouse-driven scrolling stops responding and your terminal falls back to its native scrollbar, mouse reporting is off.
|
||||
|
||||
**Apple Terminal**: Go to **View > Allow Mouse Reporting** (keyboard shortcut `Cmd+R`) to re-enable it. A checkmark appears next to the option when active.
|
||||
|
||||
**iTerm2**: Open **Settings** (`Cmd+,`) → **Profiles** → **Terminal** → ensure **"Enable mouse reporting"** is checked. Alternatively, restart iTerm2.
|
||||
|
||||
### Problem: Voice dictation records nothing
|
||||
|
||||
You start voice (`/voice` or `Ctrl+Space`), talk, and no words appear. After ~10 seconds Grok stops and shows a toast with the cause:
|
||||
|
||||
- **"microphone delivered only silence"** — the mic opens but delivers essentially zero audio. On macOS this is almost always microphone permission: the OS feeds unauthorized apps silence instead of erroring, and the permission belongs to the *terminal app* hosting Grok (Ghostty, iTerm2, …), not Grok itself. Open **System Settings → Privacy & Security → Microphone**, enable your terminal, and **restart the terminal**. If access is already allowed, check the input device and level under **System Settings → Sound → Input** (a fully muted or dead input can look the same; residual noise may instead show the “heard audio” toast).
|
||||
- **"heard audio but no speech was detected"** — audio is flowing, so the mic path is open; speak into the selected device, or try again.
|
||||
|
||||
**Verify**: Run `grok doctor` or `/terminal-setup` (with voice mode on). The **Voice** section shows the microphone Grok would capture from. Neither can detect a *denied permission* passively — macOS only reveals that once recording starts (the toast above).
|
||||
|
||||
### Problem: Byobu + GNU screen
|
||||
|
||||
Byobu on screen has best-effort support only. Prefer Byobu on tmux.
|
||||
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.
|
||||
Run `/feedback` to report it.
|
||||
|
|
|
|||
Loading…
Reference in a new issue