Synced from monorepo
Synced from monorepo Changes: - Shell: accept target response id on rewind execute - Shell: stamp response id on chat user message chunks - Worktree: optional rebuild and stale git registration cleanup in auto-GC - Worktree: kind-aware auto-GC TTLs and config knobs - Worktree: macOS process CWD scan and Unix PID liveness for GC guards - Worktree: automatic throttled GC on startup (Linux age-based; non-Linux dead-only) - Pager: add `[ui].combine_queued_prompts` to batch queued follow-ups - Shell: stop overwriting user skills - Tools: read markdown in `skills/` directories untruncated - `/usage` shows per-session token and dollar usage in the TUI - Security: prompt on environment-dumping `ps` variants - Security: always-safe `kubectl` no longer runs arbitrary kubeconfig credential plugins without permission - Tools: make scheduler deletion durable - Shell: add relocation storage primitives - Shell: give side model calls their own conversation ids - Fix five workflow-runtime bugs (budget, pause, cancel, reconnect) - Security: peel `env -S` / `--split-string` operands in the Bash permission gate (managed deny/ask) - Pager: expose doctor in the TUI - Security: block unauthorized RCE via abused safe commands - Pager idle watcher cue: "1 subagent still running" instead of "watching · 1 subagent" - Security: block `rg --pre` arbitrary code execution in auto-mode - Voice: diagnose silent-mic failures (macOS permission) and add doctor/terminal-setup Voice section - App builder deployer: `allow_forking` and `show_built_with_grok` - Pager: stop stacking duplicate "Worked for" markers on parked turns - Shell: support `max` as a distinct reasoning effort tier - Tools: serialize background `/loop` fires on the whole work unit - Shell: add working-directory relocation state primitives - Proto: `ClientToolResult` and `ChatConfig` client-side tools - Shell: model providers - Chat: select App Builder product on the Build path - Shell: attach author identity to feedback when the deployment opts in - Doctor: fix for SSH wrap setup - Workflow authoring skills: create-workflow and import-claude-workflow docs - Add read-only grok doctor - Sandbox: apply Landlock without a controlling TTY - Pager: recover image paste over grok wrap on headless remotes - Pager: make actions screen-mode aware - Shell: resume sessions when the working directory moves - Pager: centralize terminal diagnostics - Workspace: gate inline shell file access - Pager: centralize terminal probes - Pager: edit minimal prompts in an external editor - Pager: standardize backgrounding on Ctrl+B - Shell: recap rides the parent turn's prompt cache - Tools: add scheduler lifecycle version clock Source-Revision: 0f4d7c91b8b2b408333f6de1e8a76cb8eaa71899
This commit is contained in:
grokkybara[bot]
parent
a881e6703f
commit
3af4d5d398
556 changed files with 56609 additions and 21892 deletions
|
|
@ -128,9 +128,10 @@ Actions that affect the agent session, available from the agent screen.
|
|||
| `Ctrl+S` | Agent screen | Open the session picker (resume a previous session) |
|
||||
| `Ctrl+;` (alt: `Ctrl+'`) | Agent screen | Toggle the prompt queue pane (when non-empty). **Local macOS** VS Code family only: primary **`Ctrl+4`** (`;` / `'` still alts). SSH and non-Mac keep **`Ctrl+;`** / **`Ctrl+'`**. |
|
||||
| `Shift+Tab` | Prompt focused | Cycle mode (Normal → Plan → Always-approve) |
|
||||
| `Ctrl+G` | Agent screen | Send the current task to the background |
|
||||
| `Ctrl+B` | Agent screen | Send the running foreground command to the background |
|
||||
| `Ctrl+T` | Agent screen | Toggle the todos pane |
|
||||
| `Ctrl+B` | Agent screen | Toggle the tasks pane |
|
||||
| `Ctrl+G` | Agent screen (full TUI) | Toggle the tasks pane |
|
||||
| `Ctrl+G` | Ordinary composer (minimal mode) | Edit the current draft in an external editor without sending it. If the terminal reserves this chord, choose **Edit Prompt in External Editor** from the command palette. |
|
||||
| `Ctrl+L` | Agent screen | Open the extensions modal (**non–VS Code family only**; on VS Code / Cursor / Windsurf / Zed, `Ctrl+L` is mid-turn **interject** and extensions open via `/plugins` / `/hooks`) |
|
||||
| `↑` | Prompt focused (empty prompt, normal input mode) | Open the history panel with your last prompt filled in; `↑`/`↓` step through entries (each lands in the input), `↓` at the newest closes the panel, and typing edits the recalled prompt in place. Recalled `!` shell commands re-enter shell mode. `↓` never opens history. |
|
||||
| `!` | Prompt focused | Enter shell mode (type `!` on an empty prompt) |
|
||||
|
|
@ -139,9 +140,11 @@ Actions that affect the agent session, available from the agent screen.
|
|||
|
||||
**Note:** `Ctrl+M` is context-dependent. When the prompt is focused, it toggles multiline input mode. Otherwise, it opens the model picker.
|
||||
|
||||
**Note:** Minimal-mode external editing resolves `$VISUAL`, then `$EDITOR`, then `vi`. Values may include quoted arguments. Saving replaces only the draft; an empty file clears it. Drafts with pasted/file/image chips must be edited in the composer so attachments are not flattened.
|
||||
|
||||
**Note:** `Ctrl+'` is a Windows alt for `Ctrl+;` — some Windows consoles drop the `Ctrl` modifier on punctuation keys.
|
||||
|
||||
**Note:** `Ctrl+.` needs the Kitty keyboard protocol (or tmux `extended-keys on` so that protocol can pass through). On VS Code / Cursor / Windsurf / Zed integrated terminals, VTE, Apple Terminal, Windows Terminal, JetBrains, tmux with `extended-keys off`, screen, and similar no-KKP setups, Grok advertises **`Ctrl+X`** as the primary shortcuts-cheatsheet key instead. **`Ctrl+X` always works** as a classic control character even when `Ctrl+.` does not. Run `/terminal-setup` if modified keys misbehave in tmux.
|
||||
**Note:** `Ctrl+.` needs the Kitty keyboard protocol (or tmux `extended-keys on` so that protocol can pass through). On VS Code / Cursor / Windsurf / Zed integrated terminals, VTE, Apple Terminal, Windows Terminal, JetBrains, tmux with `extended-keys off`, screen, and similar no-KKP setups, Grok advertises **`Ctrl+X`** as the primary shortcuts-cheatsheet key instead. **`Ctrl+X` always works** as a classic control character even when `Ctrl+.` does not. Run `/doctor` if modified keys misbehave in tmux.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +1,10 @@
|
|||
# Slash Commands
|
||||
|
||||
Type `/` in the prompt to access commands. Each command runs an action immediately and autocompletes as you type.
|
||||
Type `/` in the prompt to open the command menu. It fuzzy-matches as you type, and picking a command runs it immediately.
|
||||
|
||||
Slash commands come from two sources:
|
||||
Commands come from two places: **shell builtins**, handled by the agent backend (xai-grok-shell), and **pager builtins**, handled by the TUI frontend (xai-grok-pager). Both show up in the same menu, and any enabled skill with `user-invocable: true` appears there too.
|
||||
|
||||
- **Shell builtins** -- handled by the agent backend (xai-grok-shell)
|
||||
- **Pager builtins** -- handled by the TUI frontend (xai-grok-pager)
|
||||
|
||||
Both sets are available in the autocomplete menu. Skills installed via SKILL.md files also appear as slash commands.
|
||||
Every command below lists its aliases where it has them. A few commands only appear when a feature or session state enables them; those cases are called out inline.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -15,70 +12,52 @@ Both sets are available in the autocomplete menu. Skills installed via SKILL.md
|
|||
|
||||
### `/new`
|
||||
|
||||
Start a new session, clearing the current conversation.
|
||||
|
||||
```
|
||||
/new
|
||||
```
|
||||
|
||||
Aliases: `/clear`
|
||||
Start a fresh session and clear the current conversation. Alias: `/clear`.
|
||||
|
||||
### `/resume`
|
||||
|
||||
Open the session picker to load a previous session from disk.
|
||||
|
||||
```
|
||||
/resume
|
||||
```
|
||||
Open the session picker to reload a previous session from disk.
|
||||
|
||||
### `/compact [context]`
|
||||
|
||||
Compress conversation history to save context window space. Optionally specify what to preserve.
|
||||
Compress conversation history to reclaim context-window space. Pass a note to tell Grok what to keep:
|
||||
|
||||
```
|
||||
/compact
|
||||
/compact keep the auth implementation details
|
||||
```
|
||||
|
||||
When the context window fills up, Grok auto-compacts at 85% usage (configurable via `[session] auto_compact_threshold_percent` in config.toml).
|
||||
Grok also auto-compacts once the context window hits 85% (tune it with `[session] auto_compact_threshold_percent`).
|
||||
|
||||
### `/context`
|
||||
|
||||
Show context window usage and session stats: a categorical breakdown (system prompt, messages, reasoning/overhead, free), plus informational rows for tool definitions, the skills listing, and MCP server announcements with their estimated token cost.
|
||||
|
||||
```
|
||||
/context
|
||||
```
|
||||
Show how the context window is being used: a category breakdown (system prompt, messages, reasoning and overhead, free space) plus informational rows for tool definitions, the skills listing, and MCP server announcements with their estimated token cost.
|
||||
|
||||
### `/session-info`
|
||||
|
||||
Show session details including model, turn count, and context usage.
|
||||
|
||||
```
|
||||
/session-info
|
||||
```
|
||||
|
||||
Show session details — model, turn count, and context usage. Aliases: `/status`, `/info`.
|
||||
|
||||
### `/fork`
|
||||
|
||||
Branch the current session into a new agent, preserving history up to this point.
|
||||
|
||||
```
|
||||
/fork
|
||||
```
|
||||
Branch the current session into a new agent, keeping history up to this point.
|
||||
|
||||
### `/rewind`
|
||||
|
||||
Rewind the conversation to an earlier turn, discarding everything after it.
|
||||
Roll the conversation back to an earlier turn and discard everything after it.
|
||||
|
||||
### `/edit-prompt`
|
||||
|
||||
In minimal mode, open an external editor for an empty composer. Grok resolves `$VISUAL`, then `$EDITOR`, then `vi`; command values may include quoted arguments. Saving replaces the draft without sending it, and saving an empty file clears it. The command is hidden outside minimal mode.
|
||||
|
||||
```
|
||||
/rewind
|
||||
/edit-prompt
|
||||
```
|
||||
|
||||
To edit an **existing** draft when a terminal or multiplexer reserves `Ctrl+G`, open the command palette and select **Edit Prompt in External Editor**. That direct route preserves the existing text and refuses pasted, file-reference, or image chips without flattening them. Typing `/edit-prompt` into the composer necessarily replaces that input, so it starts from an empty draft.
|
||||
|
||||
### `/copy`
|
||||
|
||||
Copy the most recent response to the clipboard. Pass a number to copy the Nth-latest response. Pass a file path to write instead of using the clipboard (useful over SSH when the local clipboard is unreachable).
|
||||
Every copy is also written to a backup file (`~/.grok/last-copy.txt` by default, or `GROK_COPY_FILE` if set), and the toast names that path so you always know where to retrieve the text — including when the clipboard cannot be reached (for example Apple Terminal over SSH) or the copy went out as an OSC 52 escape that this terminal couldn't be verified to apply.
|
||||
Copy the most recent response to the clipboard. Pass a number to copy the Nth-latest response instead, or a file path to write the text to a file rather than the clipboard (handy over SSH, where the local clipboard is often unreachable).
|
||||
|
||||
```
|
||||
/copy
|
||||
|
|
@ -87,51 +66,35 @@ Every copy is also written to a backup file (`~/.grok/last-copy.txt` by default,
|
|||
/copy 2 ~/exports/last-reply.md
|
||||
```
|
||||
|
||||
Every copy is also written to a backup file — `~/.grok/last-copy.txt` by default, or `GROK_COPY_FILE` if set — and the toast tells you exactly where the text landed, so you can retrieve it even when the clipboard couldn't be reached or the copy went out as an OSC 52 escape this terminal couldn't confirm.
|
||||
|
||||
### `/export`
|
||||
|
||||
Export the current conversation to a file or the clipboard.
|
||||
|
||||
```
|
||||
/export
|
||||
```
|
||||
Export the conversation to a file or the clipboard.
|
||||
|
||||
### `/quit`
|
||||
|
||||
Quit the application.
|
||||
|
||||
```
|
||||
/quit
|
||||
```
|
||||
|
||||
Aliases: `/exit`
|
||||
Quit the application. Alias: `/exit`.
|
||||
|
||||
### `/home`
|
||||
|
||||
Exit the current session and return to the welcome screen.
|
||||
|
||||
```
|
||||
/home
|
||||
```
|
||||
|
||||
Aliases: `/welcome`
|
||||
Leave the current session and return to the welcome screen. Alias: `/welcome`.
|
||||
|
||||
### `/rename`
|
||||
|
||||
Rename the current session.
|
||||
Rename the current session. Alias: `/title`.
|
||||
|
||||
```
|
||||
/rename new session title
|
||||
```
|
||||
|
||||
Aliases: `/title`
|
||||
|
||||
---
|
||||
|
||||
## Model and Mode
|
||||
|
||||
### `/model <name>`
|
||||
|
||||
Switch to a different model. Accepts model IDs or display names (case-insensitive). For reasoning models you can also pass an effort level as a second argument:
|
||||
Switch models. Accepts a model ID or display name (case-insensitive), and for reasoning models you can add an effort level as a second argument. Alias: `/m`.
|
||||
|
||||
```
|
||||
/model grok-build
|
||||
|
|
@ -139,92 +102,46 @@ Switch to a different model. Accepts model IDs or display names (case-insensitiv
|
|||
/model Reasoning X high
|
||||
```
|
||||
|
||||
Aliases: `/m`
|
||||
|
||||
### `/effort <level>`
|
||||
|
||||
Set reasoning effort on the **current** model without re-selecting it. Levels: `low`, `medium`, `high`, `xhigh`. Only works when the active model supports reasoning effort.
|
||||
Set reasoning effort on the **current** model without reselecting it. Levels are `low`, `medium`, `high`, and `xhigh`, and it only applies when the active model supports reasoning effort.
|
||||
|
||||
```
|
||||
/effort high
|
||||
/effort low
|
||||
```
|
||||
|
||||
### `/always-approve` and `/auto`
|
||||
|
||||
True **toggles** for the permission mode — both stay in the completion menu, and
|
||||
running the active mode again turns it off:
|
||||
Both are real toggles for the permission mode: they stay in the menu, and running the mode you're already in turns it back off.
|
||||
|
||||
| Command | When off | When already on |
|
||||
|---|---|---|
|
||||
| `/always-approve` | Skip all permission prompts | Back to ask |
|
||||
| `/auto` | Classifier approves safe tools (dangerous ones may still prompt) | Back to ask |
|
||||
|
||||
Running the other command while one mode is on **switches** modes (for example,
|
||||
`/auto` while always-approve is on switches to auto).
|
||||
|
||||
`/auto` is only offered when the auto permission-mode feature is enabled. You
|
||||
can also change mode with `Shift+Tab` (cycle), `Ctrl+O`, or `/settings`.
|
||||
|
||||
```
|
||||
/always-approve
|
||||
/auto
|
||||
```
|
||||
Running one while the other is active switches modes — for example, `/auto` while always-approve is on switches to auto. `/auto` only appears when the auto permission-mode feature is enabled. You can also change mode with `Shift+Tab` (cycles Normal / Plan / Always-approve), `Ctrl+O`, or `/settings`.
|
||||
|
||||
### `/multiline`
|
||||
|
||||
Toggle multiline input mode. When enabled, `Enter` inserts a newline and `Shift+Enter` (or `Alt+Enter`) sends the message. Mid-turn, bare `Enter` on an empty composer still force-sends the top queued follow-up (send now).
|
||||
|
||||
```
|
||||
/multiline
|
||||
```
|
||||
|
||||
Aliases: `/ml`
|
||||
Toggle multiline input. When it's on, `Enter` inserts a newline and `Shift+Enter` (or `Alt+Enter`) sends the message. Mid-turn, a bare `Enter` on an empty composer still force-sends the top queued follow-up. Alias: `/ml`.
|
||||
|
||||
### `/history`
|
||||
|
||||
Open the prompt-history search: fuzzy-search this session's prompts, newest first — type to filter, press `Enter`/`Tab` to drop a match back into the prompt.
|
||||
Open prompt-history search: fuzzy-search this session's prompts newest-first, then press `Enter` or `Tab` to drop a match back into the prompt.
|
||||
|
||||
For quick recall, press `↑` on an empty prompt instead: the panel opens with your most recent prompt already filled into the input, `↑`/`↓` step through entries (each one lands in the input), `↓` at the newest entry closes the panel, and typing edits the recalled prompt in place.
|
||||
|
||||
```
|
||||
/history
|
||||
```
|
||||
For quick recall, press `↑` on an empty prompt instead. The panel opens with your most recent prompt already filled in; `↑`/`↓` step through entries (each lands in the input), `↓` past the newest entry closes the panel, and typing edits the recalled prompt in place.
|
||||
|
||||
### `/compact-mode`
|
||||
|
||||
Toggle compact display mode. Reduces padding and visual spacing for denser output.
|
||||
|
||||
```
|
||||
/compact-mode
|
||||
```
|
||||
Toggle compact display — less padding and tighter spacing for denser output.
|
||||
|
||||
### `/vim-mode`
|
||||
|
||||
Toggle vim-style scrollback keybindings (j/k, h/l, g/G, y/Y, …). When off
|
||||
(default), bare-letter and `Shift+letter` keys in the scrollback focus the
|
||||
prompt and type the character. Persists to `[ui].vim_mode` in `config.toml`.
|
||||
|
||||
```
|
||||
/vim-mode
|
||||
```
|
||||
Toggle vim-style scrollback keys (`j`/`k`, `h`/`l`, `g`/`G`, `y`/`Y`, and so on). With it off (the default), a bare letter or `Shift+letter` in the scrollback just focuses the prompt and types the character. The setting persists to `[ui] vim_mode`.
|
||||
|
||||
### `/minimal` and `/fullscreen`
|
||||
|
||||
Reopen the current session in the other render mode. `/minimal` (offered in
|
||||
fullscreen) switches to the experimental scrollback-native mode; `/fullscreen`
|
||||
(offered in minimal; alias `/full`) switches back to the standard alt-screen
|
||||
TUI. Both relaunch the pager on the same conversation for this session only —
|
||||
they do not write `config.toml`. Descriptions and the relaunch banner tell you
|
||||
how to switch back (`/fullscreen` ⇄ `/minimal`). The `--minimal` /
|
||||
`--fullscreen` CLI flags are likewise session-scoped. To make plain `grok` open
|
||||
in a given mode by default, use `/settings` → **Default screen mode**, or set
|
||||
`[ui] screen_mode` in `config.toml`.
|
||||
|
||||
```
|
||||
/minimal
|
||||
/fullscreen
|
||||
```
|
||||
Reopen the current session in the other render mode. `/minimal` (offered while you're in fullscreen) switches to the experimental scrollback-native mode; `/fullscreen` (offered while you're in minimal; alias `/full`) switches back to the standard alt-screen TUI. Both relaunch the pager on the same conversation for this session only — they don't touch `config.toml`, and the relaunch banner reminds you how to switch back. The `--minimal` / `--fullscreen` CLI flags are session-scoped the same way. To make plain `grok` open in a given mode by default, use `/settings` → **Default screen mode** or set `[ui] screen_mode`.
|
||||
|
||||
### `/plan`
|
||||
|
||||
|
|
@ -236,46 +153,30 @@ Enter plan mode.
|
|||
|
||||
### `/view-plan`
|
||||
|
||||
Open the current saved plan preview. Aliases: `/show-plan`, `/plan-view`.
|
||||
|
||||
```
|
||||
/view-plan
|
||||
```
|
||||
Open a preview of the current saved plan. Aliases: `/show-plan`, `/plan-view`.
|
||||
|
||||
---
|
||||
|
||||
## Memory
|
||||
|
||||
The `/flush`, `/dream`, and `/memory` commands require `--experimental-memory` or `GROK_MEMORY=1`. `/remember` is always available.
|
||||
`/flush`, `/dream`, and `/memory` require memory to be enabled (`--experimental-memory` or `GROK_MEMORY=1`); `/memory` also needs a configured memory backend. `/remember` is always available.
|
||||
|
||||
### `/memory`
|
||||
|
||||
Browse, view, and manage your saved memories. Pass `on` or `off` to enable or disable memory.
|
||||
Browse, view, and manage saved memories. Pass `on` or `off` to enable or disable memory. Alias: `/mem`.
|
||||
|
||||
```
|
||||
/memory
|
||||
/memory off
|
||||
```
|
||||
|
||||
Aliases: `/mem`
|
||||
|
||||
### `/flush`
|
||||
|
||||
Save current session knowledge to memory immediately. Triggers an LLM-generated summary of the session's most important content.
|
||||
|
||||
```
|
||||
/flush
|
||||
```
|
||||
|
||||
Use this when you want to preserve important context before compaction or at any point in a session.
|
||||
Save the current session's knowledge to memory right now, triggering an LLM summary of the most important content. Reach for it before compaction, or any time you want to lock in context.
|
||||
|
||||
### `/dream`
|
||||
|
||||
Run memory consolidation -- merge session logs into organized topics.
|
||||
|
||||
```
|
||||
/dream
|
||||
```
|
||||
Run memory consolidation — merge session logs into organized topics.
|
||||
|
||||
### `/remember`
|
||||
|
||||
|
|
@ -289,47 +190,28 @@ Save a note to memory immediately, without waiting for an automatic summary.
|
|||
|
||||
## Hooks and Plugins
|
||||
|
||||
The `/hooks`, `/plugins`, `/marketplace`, and `/skills` commands open the same extensions modal on different tabs.
|
||||
`/hooks`, `/plugins`, `/marketplace`, and `/skills` all open the same extensions modal, each on its own tab.
|
||||
|
||||
### `/hooks`
|
||||
|
||||
Open the extensions modal on the Hooks tab. From the modal you can view loaded hooks, add or remove custom hooks, and enable or disable them individually. The modal does not grant project trust -- see [10-hooks.md](10-hooks.md) for the trust model.
|
||||
Open the extensions modal on the Hooks tab, where you can view loaded hooks, add or remove custom ones, and toggle them individually. The modal does not grant project trust — see [10-hooks.md](10-hooks.md) for the trust model.
|
||||
|
||||
```
|
||||
/hooks
|
||||
```
|
||||
|
||||
**Note:** The shell advertises individual `/hooks-list`, `/hooks-trust`, `/hooks-add`, `/hooks-remove`,
|
||||
and `/hooks-untrust` commands. In the TUI pager, these are consolidated into the `/hooks` modal.
|
||||
The shell also advertises individual `/hooks-list`, `/hooks-trust`, `/hooks-add`, `/hooks-remove`, and `/hooks-untrust` commands; in the TUI pager these are folded into the `/hooks` modal.
|
||||
|
||||
### `/plugins`
|
||||
|
||||
Open the extensions modal on the Plugins tab. From the modal you can view installed plugins, install new ones from the marketplace, and manage trust.
|
||||
Open the extensions modal on the Plugins tab to view installed plugins, install new ones from the marketplace, and manage trust.
|
||||
|
||||
```
|
||||
/plugins
|
||||
```
|
||||
|
||||
The shell also supports subcommands (`/plugins list`, `/plugins install <source>`,
|
||||
`/plugins uninstall <name>`, `/plugins update`). In the TUI, the `/plugins` modal
|
||||
provides the same functionality with a visual interface.
|
||||
The shell additionally supports subcommands (`/plugins list`, `/plugins install <source>`, `/plugins uninstall <name>`, `/plugins update`, `/plugins reload`). In the TUI, the modal does the same work visually.
|
||||
|
||||
### `/marketplace`
|
||||
|
||||
Open the extensions modal on the Marketplace tab to browse and install plugins.
|
||||
|
||||
```
|
||||
/marketplace
|
||||
```
|
||||
|
||||
### `/skills`
|
||||
|
||||
Open the extensions modal on the Skills tab to view installed skills.
|
||||
|
||||
```
|
||||
/skills
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Media Generation
|
||||
|
|
@ -344,7 +226,7 @@ Generate an image from a text description.
|
|||
|
||||
### `/imagine-video <description>`
|
||||
|
||||
Generate a video from an image or text description. Plans shots, generates source images, and animates them with `image_to_video`.
|
||||
Generate a video from a text (or image) description. It plans shots, generates source images, and animates them with `image_to_video`.
|
||||
|
||||
```
|
||||
/imagine-video a cat playing piano in a jazz club
|
||||
|
|
@ -356,41 +238,72 @@ Generate a video from an image or text description. Plans shots, generates sourc
|
|||
|
||||
### `/loop [interval] <prompt>`
|
||||
|
||||
Run a prompt on a recurring interval. Specify the interval as `30m`, `1 hour`, or `every 2 days`. If you omit it, Grok prompts you.
|
||||
Run a prompt on a recurring interval. Give the interval as `30m`, `1 hour`, or `every 2 days`; leave it out and Grok will ask.
|
||||
|
||||
```
|
||||
/loop 30m check deploy status
|
||||
/loop check deploy status every hour
|
||||
```
|
||||
|
||||
Interval format: `Ns` (seconds, min 60), `Nm` (minutes), `Nh` (hours), `Nd` (days). Intervals under 60 seconds are raised to the 60-second minimum.
|
||||
Intervals are `Ns` (seconds, minimum 60), `Nm` (minutes), `Nh` (hours), or `Nd` (days); anything under 60 seconds is raised to the minimum. Recurring tasks expire after 7 days, and you can cancel one with `scheduler_delete` using the job ID reported when the loop is created.
|
||||
|
||||
Recurring tasks auto-expire after 7 days. Cancel with `scheduler_delete` (the job ID is provided when the loop is created).
|
||||
---
|
||||
|
||||
## Workflows and Goals
|
||||
|
||||
### `/goal`
|
||||
|
||||
Set, manage, or check an autonomous goal. Grok works across rounds and only marks the goal complete after an independent evidence review confirms the claim; if that review can't reproduce the result or has no usable evidence, the goal stays active or pauses with concrete gaps.
|
||||
|
||||
```
|
||||
/goal Migrate the auth module to the new API
|
||||
/goal status
|
||||
/goal pause
|
||||
/goal resume
|
||||
/goal clear
|
||||
```
|
||||
|
||||
Arguments are `<objective> [--budget <tokens>]`, or one of `status`, `pause`, `resume`, `clear`. The `--budget` here is a **token** budget for the goal run, separate from the agent-count budgets that workflows use. `/goal` appears when goal mode is enabled for the session. Which driver runs it depends on background workflows: with them on, the host evaluates each model round and runs adversarial verification on completion candidates; with them off, the legacy model-facing `update_goal` path reports progress and triggers verification.
|
||||
|
||||
### `/deep-research <query>`
|
||||
|
||||
Kick off a background research workflow. It plans a bounded set of questions, gathers structured claims with source evidence, cross-checks each claim on an independent verifier shard, and renders only the claims that survive, with their verified source locators. Failed shards, dropped claims, and researcher uncertainties are reported as coverage limitations, and the report is marked **Partial** whenever any remain.
|
||||
|
||||
```
|
||||
/deep-research Compare the migration risks of PostgreSQL 17 and MySQL 9
|
||||
```
|
||||
|
||||
The command returns right away — follow progress in `/workflows`, and the final report appears in the conversation on its own.
|
||||
|
||||
Model-launched workflows may set `agent_budget` on the `workflow` tool. It's an absolute cumulative cap on logical child-agent calls: every `agent()` call and every item in a `parallel()` panel spends one slot, while schema-correction retries don't. The default is 128, explicit values run 1–1,024, and a panel that would cross the remaining budget is rejected before any of its children launch. `budget()` reports the cap as `total`, admitted calls as `spent`, `reserved` (always zero), and `remaining`. Named slash launches use the default budget.
|
||||
|
||||
### `/workflow`
|
||||
|
||||
Launch a saved workflow, or manage a running one by the session-unique display name shown in `/workflows`. Launch the same workflow twice and the display names are numbered (`review-changes`, `review-changes-2`); you never need the internal run IDs.
|
||||
|
||||
```
|
||||
/workflow review-changes {"target":"origin/main...HEAD"}
|
||||
/workflow pause review-changes
|
||||
/workflow resume review-changes
|
||||
/workflow stop review-changes-2
|
||||
/workflow save review-changes
|
||||
```
|
||||
|
||||
Project workflows live in `.grok/workflows/*.rhai`; user workflows live in `~/.grok/workflows/*.rhai`. A same-process pause/resume continues the original immutable script, args, and `agent_budget` cap from committed host-call results — to iterate, edit the returned script copy and launch it as a new run.
|
||||
|
||||
A budget-limited run is different: it only resumes through a model/tool resume request that supplies an `agent_budget` above the admitted agent count. A bare `/workflow resume <name>` can't raise the cap, so it rejects budget-limited runs. Runs interrupted by a process restart aren't resumed at all, because external effects have no stable cross-process identity. And resume is not exactly-once: an external effect whose result wasn't committed before a same-process pause can run again.
|
||||
|
||||
### `/workflows`
|
||||
|
||||
Open the live workflows **run** dashboard — active and retained runs, not a catalog of saved definitions. Each row shows the run's display name, phase, agent roster, progress, and result. Inside a run's detail view, `p` pauses, `r` resumes an ordinary pause, and `x` stops. Budget-limited runs can't bare-resume: `r` returns the shell's rejection (raise the cap with a model/tool resume that passes a higher `agent_budget`), while `x` still stops. `s` saves the run's script, but it's hidden for known built-ins and numbered duplicate handles — for those, choose a new unique `meta.name` and save the edited script explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Other
|
||||
|
||||
### `/goal`
|
||||
|
||||
Set, manage, or check an autonomous goal. Grok works toward the objective across turns and reports progress.
|
||||
|
||||
```
|
||||
/goal Migrate the auth module to the new API
|
||||
/goal status
|
||||
```
|
||||
|
||||
Arguments: `<objective>`, `status`, `pause`, `resume`, or `clear`. **Availability:** appears only when the goal feature is enabled and the `update_goal` tool is in the session toolset.
|
||||
|
||||
### `/theme`
|
||||
|
||||
Switch the TUI color theme.
|
||||
|
||||
```
|
||||
/theme
|
||||
```
|
||||
|
||||
Aliases: `/t`
|
||||
Switch the TUI color theme. Alias: `/t`.
|
||||
|
||||
### `/feedback [message]`
|
||||
|
||||
|
|
@ -402,11 +315,7 @@ Report an issue or send feedback.
|
|||
|
||||
### `/btw`
|
||||
|
||||
Send an aside to the agent without interrupting the current task. In minimal
|
||||
mode (`--minimal`), the answer appears in a dismissible panel above the prompt.
|
||||
**Esc** dismisses the panel; a finished answer is saved into native scrollback,
|
||||
while a late response to a dismissed loading panel is dropped. Side Q/A is not
|
||||
part of the main turn.
|
||||
Send an aside to the agent without interrupting the current task. In minimal mode (`--minimal`), the answer shows up in a dismissible panel above the prompt: `Esc` dismisses it, a finished answer is saved into native scrollback, and a late reply to an already-dismissed panel is dropped. The side question and its answer aren't part of the main turn.
|
||||
|
||||
```
|
||||
/btw also check the error handling
|
||||
|
|
@ -416,33 +325,17 @@ part of the main turn.
|
|||
|
||||
Open the MCP servers management modal.
|
||||
|
||||
```
|
||||
/mcps
|
||||
```
|
||||
### `/doctor`
|
||||
|
||||
### `/terminal-setup`
|
||||
|
||||
Show terminal capability detection and setup info — including color level, which themes are available, clipboard routes, and fix instructions for common issues (truecolor, tmux clipboard, keyboard protocol).
|
||||
|
||||
```
|
||||
/terminal-setup
|
||||
```
|
||||
|
||||
Aliases: `/terminal-check`, `/terminal-info`
|
||||
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`.
|
||||
|
||||
### `/release-notes`
|
||||
|
||||
View release notes for the current version.
|
||||
|
||||
```
|
||||
/release-notes
|
||||
```
|
||||
|
||||
Aliases: `/changelog`
|
||||
View release notes for the current version. Alias: `/changelog`.
|
||||
|
||||
### `/docs`
|
||||
|
||||
Browse in-TUI How-to Guides, open online Build docs, or jump to a guide by title.
|
||||
Browse the in-TUI How-to Guides, open the online Build docs, or jump straight to a guide by title. Aliases: `/howto`, `/guides`.
|
||||
|
||||
```
|
||||
/docs
|
||||
|
|
@ -450,19 +343,13 @@ Browse in-TUI How-to Guides, open online Build docs, or jump to a guide by title
|
|||
/docs Getting Started
|
||||
```
|
||||
|
||||
- Bare `/docs` (or `/docs how-to`) opens the How-to Guides picker
|
||||
- `/docs web` opens https://docs.x.ai/build/overview in the browser
|
||||
- `/docs <title>` opens a specific guide (case-insensitive title match)
|
||||
|
||||
Aliases: `/howto`, `/guides`
|
||||
- Bare `/docs` (or `/docs how-to`) opens the How-to Guides picker.
|
||||
- `/docs web` opens https://docs.x.ai/build/overview in your browser.
|
||||
- `/docs <title>` opens a specific guide by case-insensitive title match.
|
||||
|
||||
### `/import-claude`
|
||||
|
||||
Open the Claude settings import modal to bring over `~/.claude` settings: permissions, environment variables, MCP servers, hooks, and paths.
|
||||
|
||||
```
|
||||
/import-claude
|
||||
```
|
||||
Open the Claude import modal to bring over `~/.claude` settings: permissions, environment variables, MCP servers, hooks, and paths.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -470,21 +357,11 @@ Open the Claude settings import modal to bring over `~/.claude` settings: permis
|
|||
|
||||
### `/config-agents`
|
||||
|
||||
Open the agents modal to view and manage agent definitions, set the default agent, and switch the active one.
|
||||
|
||||
```
|
||||
/config-agents
|
||||
```
|
||||
|
||||
Aliases: `/agents`
|
||||
Open the agents modal to view and manage agent definitions, set the default, and switch the active one. Alias: `/agents`.
|
||||
|
||||
### `/personas`
|
||||
|
||||
Manage personas -- create, edit, and delete personas. A subagent can apply a persona to shape its behavior.
|
||||
|
||||
```
|
||||
/personas
|
||||
```
|
||||
Create, edit, and delete personas. A subagent can apply a persona to shape how it behaves.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -492,26 +369,19 @@ Manage personas -- create, edit, and delete personas. A subagent can apply a per
|
|||
|
||||
### `/login`
|
||||
|
||||
Log in or re-authenticate with your account without leaving the session.
|
||||
|
||||
```
|
||||
/login
|
||||
```
|
||||
Log in or re-authenticate without leaving the session.
|
||||
|
||||
### `/logout`
|
||||
|
||||
Log out and return to the login screen.
|
||||
|
||||
```
|
||||
/logout
|
||||
```
|
||||
|
||||
### `/usage`
|
||||
|
||||
View credit usage or manage billing.
|
||||
View credit usage or manage billing. Alias: `/cost`.
|
||||
|
||||
```
|
||||
/usage
|
||||
/usage manage
|
||||
```
|
||||
|
||||
### `/privacy`
|
||||
|
|
@ -524,11 +394,7 @@ Show or toggle privacy and data-retention status.
|
|||
/privacy opt-out
|
||||
```
|
||||
|
||||
Does not change `[features] telemetry`, `trace_upload`, or external OTEL settings.
|
||||
See [Monitoring Usage](24-monitoring-usage.md#related-settings).
|
||||
On team accounts, only a team admin can toggle privacy with `/privacy`.
|
||||
Team admins can also enable or disable Zero Data Retention (ZDR) for their team:
|
||||
[How to enable ZDR](https://docs.x.ai/developers/faq/security#how-to-enable-zdr).
|
||||
`/privacy` doesn't touch `[features] telemetry`, `trace_upload`, or your external OTEL settings — see [Monitoring Usage](24-monitoring-usage.md#related-settings). On team accounts, only a team admin can toggle privacy this way, and admins can also enable or disable Zero Data Retention for the team ([how to enable ZDR](https://docs.x.ai/developers/faq/security#how-to-enable-zdr)).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -536,50 +402,33 @@ Team admins can also enable or disable Zero Data Retention (ZDR) for their team:
|
|||
|
||||
### `/settings`
|
||||
|
||||
Open the settings modal to view and change configuration interactively.
|
||||
|
||||
```
|
||||
/settings
|
||||
```
|
||||
|
||||
Aliases: `/config`, `/preferences`, `/prefs`
|
||||
Open the settings modal to view and change configuration interactively. Aliases: `/config`, `/preferences`, `/prefs`.
|
||||
|
||||
### `/timestamps`
|
||||
|
||||
Toggle message timestamps on or off.
|
||||
|
||||
```
|
||||
/timestamps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skills as Slash Commands
|
||||
|
||||
Any enabled skill with `user-invocable: true` in its SKILL.md frontmatter appears as a slash command. (A skill turned off via `/skills` is not advertised.) For example, if you have a skill at `~/.grok/skills/commit/SKILL.md`, you can invoke it with:
|
||||
Any enabled skill with `user-invocable: true` in its SKILL.md frontmatter shows up as a slash command. (Turn a skill off via `/skills` and it stops being advertised.) So a skill at `~/.grok/skills/commit/SKILL.md` runs as:
|
||||
|
||||
```
|
||||
/commit fix typo in README
|
||||
```
|
||||
|
||||
Skills from plugins also appear as slash commands. When multiple skills share the same name (across scopes), use the qualified form:
|
||||
Skills from plugins work the same way. When two skills share a name across scopes, qualify it:
|
||||
|
||||
```
|
||||
/local:commit # Project-scoped skill
|
||||
/user:commit # User-scoped skill
|
||||
```
|
||||
|
||||
Built-in slash commands always take priority over skills with the same name. If you name a skill "compact", typing `/compact` will run the built-in compact command, but `/local:compact` will invoke the skill.
|
||||
Built-in commands always win over a skill with the same name. Name a skill "compact" and `/compact` still runs the built-in — but `/local:compact` invokes the skill.
|
||||
|
||||
---
|
||||
|
||||
## Autocomplete
|
||||
|
||||
The slash command menu supports fuzzy search. Start typing after `/` to filter available commands. The menu shows:
|
||||
|
||||
- Command name
|
||||
- Description
|
||||
- Argument hint (if the command accepts arguments)
|
||||
- Source (builtin, skill scope, plugin name)
|
||||
|
||||
Press `Tab` or `Enter` to select a command from the autocomplete menu.
|
||||
The menu supports fuzzy search: start typing after `/` to filter. Each entry shows the command name, its description, an argument hint when it takes arguments, and its source (builtin, skill scope, or plugin name). Press `Tab` or `Enter` to accept the highlighted command.
|
||||
|
|
|
|||
|
|
@ -1,37 +1,33 @@
|
|||
# Configuration
|
||||
|
||||
Grok reads configuration from local config files, environment variables, and
|
||||
CLI flags. This document covers the common options.
|
||||
Grok reads settings from config files, environment variables, and CLI flags. This page covers the common options.
|
||||
|
||||
---
|
||||
|
||||
## Precedence
|
||||
|
||||
Configuration is resolved in this order (highest priority first):
|
||||
Settings resolve highest-priority first:
|
||||
|
||||
1. **CLI flags** (e.g., `--yolo`, `--model`, `--sandbox`)
|
||||
2. **Environment variables** (e.g., `XAI_API_KEY`, `GROK_MEMORY`)
|
||||
1. **CLI flags** (e.g. `--yolo`, `--model`, `--sandbox`)
|
||||
2. **Environment variables** (e.g. `XAI_API_KEY`, `GROK_MEMORY`)
|
||||
3. **config.toml** (`~/.grok/config.toml`)
|
||||
4. **Managed / requirements config** (local files your org may deploy, e.g.
|
||||
`managed_config.toml` / `requirements.toml`)
|
||||
4. **Managed / requirements config** (files your org may deploy, e.g. `managed_config.toml` / `requirements.toml`)
|
||||
5. **Built-in defaults**
|
||||
|
||||
---
|
||||
|
||||
## config.toml (Main Configuration)
|
||||
## config.toml (main configuration)
|
||||
|
||||
Location: `~/.grok/config.toml`
|
||||
Location: `~/.grok/config.toml`. If the file is missing, Grok uses its built-in defaults, so you only need to set the values you want to override.
|
||||
|
||||
If the file does not exist, Grok uses built-in defaults. Specify only the values you want to override.
|
||||
|
||||
### General Settings
|
||||
### General settings
|
||||
|
||||
```toml
|
||||
[cli]
|
||||
auto_update = true # check for updates on launch
|
||||
|
||||
[models]
|
||||
default = "grok-build" # model used for new sessions
|
||||
default = "grok-build" # model used for new sessions
|
||||
web_search = "grok-4.20-multi-agent" # model used by the web_search tool
|
||||
|
||||
# Defaults applied to every model; a per-model [model.<id>] value always wins.
|
||||
|
|
@ -45,7 +41,7 @@ inference_idle_timeout_secs = 600
|
|||
stream_tool_calls = true
|
||||
|
||||
[ui]
|
||||
simple_mode = true # readline-style prompt editing (default); false = vim editing in the prompt
|
||||
simple_mode = true # readline-style prompt editing (default); false = vim editing in the prompt
|
||||
vim_mode = false # vim-style scrollback navigation keys (default: false)
|
||||
max_thoughts_width = 120 # max column width for reasoning display
|
||||
default_selected_permission = "always_allow_all_sessions" # preselected row on the FIRST approval prompt
|
||||
|
|
@ -68,30 +64,28 @@ screen_mode = "fullscreen" # default render mode: "fullscreen" | "mi
|
|||
telemetry = false # anonymous usage telemetry
|
||||
feedback = true # feedback system (default: true)
|
||||
lsp_tools = false # expose the lsp tool
|
||||
codebase_indexing = true # code graph indexing
|
||||
codebase_indexing = true # code graph indexing (default: true)
|
||||
two_pass_compaction = false # prefire two-pass compaction (default: false, opt-in)
|
||||
remote_fetch = true # allow optional online model-catalog fetches (default: true;
|
||||
# set false for firewalled/air-gapped deployments; background
|
||||
# managed-config sync has its own switch: managed_config)
|
||||
|
||||
[session]
|
||||
auto_compact_threshold_percent = 85 # auto-compact at this % of context window
|
||||
auto_compact_threshold_percent = 85 # auto-compact at this % of context window (default: 85)
|
||||
load_envrc = true # load .envrc environment variables
|
||||
|
||||
[tools]
|
||||
respect_gitignore = false # default: false; set true to make every tool skip gitignored files
|
||||
```
|
||||
|
||||
#### Input Mode
|
||||
#### Input mode
|
||||
|
||||
The `simple_mode` setting under `[ui]` controls how you edit text in the
|
||||
**prompt** — the input editor. It does not change how you navigate the
|
||||
scrollback; that is governed separately by [`vim_mode`](#vim-mode).
|
||||
`[ui] simple_mode` controls how you edit text in the **prompt** — the input editor. It has nothing to do with how you move around the scrollback; that's [`vim_mode`](#vim-mode).
|
||||
|
||||
| Value | Behavior |
|
||||
|-------|----------|
|
||||
| `true` (default) | **Readline editing.** The prompt uses plain readline-style text entry. |
|
||||
| `false` | **Vim editing (experimental).** The prompt uses vim-style modal editing (normal and insert modes). When the prompt is empty, it starts in normal mode with focus on the scrollback. |
|
||||
| `true` (default) | **Readline editing.** Plain readline-style text entry. |
|
||||
| `false` | **Vim editing (experimental).** Vim-style modal editing (normal and insert modes). When the prompt is empty it starts in normal mode with focus on the scrollback. |
|
||||
|
||||
To switch the prompt to vim-style editing:
|
||||
|
||||
|
|
@ -100,20 +94,11 @@ To switch the prompt to vim-style editing:
|
|||
simple_mode = false
|
||||
```
|
||||
|
||||
You can also toggle this setting from the settings pane (`/settings` →
|
||||
**Disable vim input mode**); Grok writes your choice to `[ui] simple_mode` in
|
||||
`config.toml`.
|
||||
You can also flip it from the settings pane (`/settings` → **Disable vim input mode**); Grok writes your choice to `[ui] simple_mode`. `simple_mode` and `vim_mode` are independent — one governs the prompt editor, the other governs scrollback navigation. See [Keyboard Shortcuts](03-keyboard-shortcuts.md) for the full binding reference.
|
||||
|
||||
`simple_mode` and `vim_mode` are independent: `simple_mode` changes the prompt
|
||||
editor, and `vim_mode` changes scrollback navigation. See [Keyboard Shortcuts](03-keyboard-shortcuts.md)
|
||||
for the full binding reference.
|
||||
#### Default selected permission
|
||||
|
||||
#### Default Selected Permission
|
||||
|
||||
When the agent asks for permission to run a command (or other tool action),
|
||||
the approval menu highlights one row by default — the cursor row. The
|
||||
`default_selected_permission` setting under `[ui]` controls which row that
|
||||
is on the **first** prompt of a session.
|
||||
When the agent asks to run a command (or take some other tool action), the approval menu highlights one row by default. `[ui] default_selected_permission` sets which row that is on the **first** prompt of a session.
|
||||
|
||||
| Value | Preselected row |
|
||||
|-------|-----------------|
|
||||
|
|
@ -127,59 +112,30 @@ is on the **first** prompt of a session.
|
|||
default_selected_permission = "allow_once"
|
||||
```
|
||||
|
||||
After you answer the first prompt, the cursor becomes **sticky**: each later
|
||||
prompt preselects the same kind of choice you last confirmed (e.g. once you
|
||||
pick "No", subsequent prompts start on their reject row), carrying across edit
|
||||
/ bash / MCP prompts until you restart. So `default_selected_permission` only
|
||||
sets the starting point.
|
||||
After you answer the first prompt the cursor turns **sticky**: each later prompt preselects whatever you last confirmed (pick "No" once and subsequent prompts start on their reject row), carrying across edit / bash / MCP prompts until you restart. So this setting only picks the starting point.
|
||||
|
||||
The accepted values are `always_allow_all_sessions`, `allow_command_always`,
|
||||
`allow_once`, and `reject` (matching case-insensitively). When the key is unset
|
||||
— or set to any unrecognized value — it falls back to `always_allow_all_sessions`.
|
||||
The `allow_command_always` row is scoped to the specific action being approved
|
||||
(command / tool / domain / edit-session), never a global allow-everything —
|
||||
that is `always_allow_all_sessions`. Note that the per-command "Always allow"
|
||||
rows appear only when `[ui] remember_tool_approvals = true` (default: false).
|
||||
See [22-permissions-and-safety.md](22-permissions-and-safety.md).
|
||||
Values match case-insensitively; an unset or unrecognized value falls back to `always_allow_all_sessions`. The `allow_command_always` row is always scoped to the specific action being approved (command / tool / domain / edit-session), never a global allow-everything — that's what `always_allow_all_sessions` is for. Note the per-command "Always allow" rows only appear when `[ui] remember_tool_approvals = true` (default false). See [22-permissions-and-safety.md](22-permissions-and-safety.md).
|
||||
|
||||
The setting can also be overridden with the `GROK_DEFAULT_SELECTED_PERMISSION`
|
||||
environment variable — handy for headless / agent test runs that shouldn't
|
||||
mutate `config.toml`. Precedence: env var → `config.toml` →
|
||||
`always_allow_all_sessions` (the default).
|
||||
You can also override this with `GROK_DEFAULT_SELECTED_PERMISSION`, which is handy for headless or agent test runs that shouldn't mutate `config.toml`. Precedence: env var → `config.toml` → `always_allow_all_sessions`.
|
||||
|
||||
#### Vim Mode
|
||||
#### Vim mode
|
||||
|
||||
The `vim_mode` setting under `[ui]` controls whether vim-style bindings are
|
||||
active in the **scrollback** pane. It does not affect the input prompt.
|
||||
`[ui] vim_mode` controls whether vim-style bindings are active in the **scrollback** pane. It does not affect the prompt.
|
||||
|
||||
| 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 of those letters focuses the prompt and types the character. Arrows, `Tab`, `Space`, `PageUp`/`PageDown`, and all `Ctrl+letter` shortcuts still navigate the scrollback. `Esc` is **not** a scrollback navigation key — it follows clear / rewind / mid-turn-swallow policy (see [Keyboard Shortcuts](03-keyboard-shortcuts.md#escape)). |
|
||||
| `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). |
|
||||
|
||||
Toggle `vim_mode` at runtime with `/vim-mode`, or from the settings pane
|
||||
(`/settings` → **Vim scrollback navigation**). Grok writes the change to
|
||||
`[ui] vim_mode` in `~/.grok/config.toml` immediately and applies it to every
|
||||
future pager session — including new agents and subagents started in the same
|
||||
process. There is no separate per-session override; whatever is in
|
||||
`config.toml` is the source of truth on next launch.
|
||||
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`.
|
||||
|
||||
`vim_mode` is independent of `simple_mode`: `vim_mode` controls scrollback
|
||||
navigation, while `simple_mode` controls editing in the prompt.
|
||||
#### Screen mode
|
||||
|
||||
#### Screen Mode
|
||||
|
||||
The `screen_mode` setting under `[ui]` is the **default render mode** for plain
|
||||
`grok` launches. Configure it from `/settings` → **Default screen mode**
|
||||
(restart required), or edit `config.toml` by hand. Both choices write
|
||||
`config.toml`. CLI flags (`--minimal` / `--fullscreen`) and slash commands
|
||||
(`/minimal` / `/fullscreen`) are session-scoped and do **not** write this key —
|
||||
after a slash switch, the reverse command (`/fullscreen` ⇄ `/minimal`) returns
|
||||
you for that session only.
|
||||
`[ui] screen_mode` is the **default render mode** for plain `grok` launches. Set it from `/settings` → **Default screen mode** (restart required) or edit `config.toml` by hand — both write the file. CLI flags (`--minimal` / `--fullscreen`) and slash commands (`/minimal` / `/fullscreen`) are session-scoped and do **not** write this key; after a slash switch, the reverse command returns you for that session only.
|
||||
|
||||
| Value | Behavior |
|
||||
|-------|----------|
|
||||
| unset | Settings shows **Fullscreen**. At startup there is no sticky preference: legacy `pager.toml` `[terminal] minimal` can still force minimal, and terminals that leak mouse reports (JediTerm/Windows) may auto-open minimal until you set an explicit value. Otherwise the alt-screen policy picks fullscreen vs inline. |
|
||||
| unset | Settings shows **Fullscreen**. There's no sticky preference at startup: legacy `pager.toml` `[terminal] minimal` can still force minimal, and terminals that leak mouse reports (JediTerm/Windows) may auto-open minimal until you set an explicit value. Otherwise the alt-screen policy picks fullscreen vs inline. |
|
||||
| `"fullscreen"` | Sticky non-minimal. Fullscreen-vs-inline still follows the alt-screen policy (`--no-alt-screen`, `[terminal] alt_screen`, terminal auto-detection). |
|
||||
| `"minimal"` | Sticky minimal (scrollback-native) mode. |
|
||||
|
||||
|
|
@ -187,24 +143,17 @@ A CLI flag always wins over the config value for that invocation.
|
|||
|
||||
#### Snap prompt to top on send
|
||||
|
||||
By default, sending a prompt scrolls it to the top of the viewport so the
|
||||
response starts on a fresh page. Set `[ui] page_flip_on_send = false` (or
|
||||
toggle **Snap prompt to top on send** in `/settings` → Appearance) to leave
|
||||
the scroll position unchanged when you send. Applies on the next send; no
|
||||
restart.
|
||||
By default, sending a prompt scrolls it to the top of the viewport so the response starts on a fresh page. Set `[ui] page_flip_on_send = false` (or toggle **Snap prompt to top on send** in `/settings` → Appearance) to leave the scroll position alone when you send. It takes effect on the next send — no restart.
|
||||
|
||||
#### Scrolling
|
||||
|
||||
Four `[ui]` settings tune mouse-wheel and trackpad scrolling in the
|
||||
scrollback. All apply immediately (no restart) and are editable from the
|
||||
settings pane (`/settings` → **Scroll speed** / **Scroll input** /
|
||||
**Scroll lines** / **Invert scroll**).
|
||||
Four `[ui]` settings tune mouse-wheel and trackpad scrolling. All apply immediately and are editable from the settings pane (`/settings` → **Scroll speed** / **Scroll input** / **Scroll lines** / **Invert scroll**).
|
||||
|
||||
| Key | Values (default) | Behavior |
|
||||
|-----|------------------|----------|
|
||||
| `scroll_speed` | `1`–`100` (`50`) | Speed multiplier for both wheel and trackpad. `50` = 1.0x, `1` = 0.1x, `100` = 6.0x. |
|
||||
| `scroll_mode` | `auto` \| `wheel` \| `trackpad` (`auto`) | Wheel-vs-trackpad detection is heuristic (terminal scroll events carry no magnitude); force one kind when auto-detection misreads your device — e.g. a wheel notch that jumps too far, or a trackpad that feels stepped. |
|
||||
| `scroll_lines` | `1`–`10` (unset) | Lines per scroll tick, applied to **both** wheel and trackpad. While unset, each terminal's own profile applies (e.g. a conservative 1 line/event under tmux). Committing any value — even `3`, the number the settings pane displays — switches permanently to that explicit override. |
|
||||
| `scroll_speed` | `1`–`100` (`50`) | Speed multiplier for wheel and trackpad. `50` = 1.0x, `1` = 0.1x, `100` = 6.0x. |
|
||||
| `scroll_mode` | `auto` \| `wheel` \| `trackpad` (`auto`) | Wheel-vs-trackpad detection is heuristic (terminal scroll events carry no magnitude); force one when auto-detection misreads your device — e.g. a wheel notch that jumps too far, or a trackpad that feels stepped. |
|
||||
| `scroll_lines` | `1`–`10` (unset) | Lines per scroll tick, applied to **both** wheel and trackpad. While unset, each terminal's own profile applies (e.g. a conservative 1 line/event under tmux). Committing any value — even `3`, the number the settings pane shows — switches permanently to that explicit override. |
|
||||
| `invert_scroll` | `false` \| `true` (`false`) | Reverse vertical scroll direction ("natural" scrolling). |
|
||||
|
||||
```toml
|
||||
|
|
@ -216,14 +165,9 @@ invert_scroll = false
|
|||
# scroll_lines = 3
|
||||
```
|
||||
|
||||
Each setting also has an environment-variable override, applied on first load
|
||||
only — handy for headless / test runs that shouldn't mutate `config.toml`:
|
||||
`GROK_SCROLL_SPEED`, `GROK_SCROLL_MODE`, `GROK_INVERT_SCROLL`
|
||||
(`1`/`true`/`0`/`false`), and `GROK_SCROLL_LINES`. Precedence: env var →
|
||||
`config.toml` → default. Unrecognized values fall back to the default, and
|
||||
out-of-range numbers clamp to the allowed range.
|
||||
Each setting also has an environment-variable override, applied on first load only (again, handy for headless / test runs): `GROK_SCROLL_SPEED`, `GROK_SCROLL_MODE`, `GROK_INVERT_SCROLL` (`1`/`true`/`0`/`false`), and `GROK_SCROLL_LINES`. Precedence: env var → `config.toml` → default. Unrecognized values fall back to the default, and out-of-range numbers clamp.
|
||||
|
||||
### Tool Configuration
|
||||
### Tool configuration
|
||||
|
||||
```toml
|
||||
[toolset.bash]
|
||||
|
|
@ -236,28 +180,17 @@ timeout_secs = 1800 # seconds to wait when enabled (default:
|
|||
|
||||
[toolset.web_fetch]
|
||||
proxy_endpoint = "https://proxy.example.com" # egress proxy URL
|
||||
allowed_domains = ["docs.rs", "x.ai"] # override the built-in allowlist
|
||||
allow_local = false # true = allow localhost / 127.0.0.0/8 / ::1 only
|
||||
allowed_domains = ["docs.rs", "x.ai"] # override the built-in allowlist
|
||||
allow_local = false # true = allow localhost / 127.0.0.0/8 / ::1 only
|
||||
```
|
||||
|
||||
`allow_local` is off by default (SSRF fail-closed). When `true` (or
|
||||
`GROK_WEB_FETCH_ALLOW_LOCAL=1`), `web_fetch` may reach **explicit** loopback
|
||||
hosts only — private, link-local, and cloud-metadata ranges stay blocked.
|
||||
Resolution: TOML > env > default off.
|
||||
`allow_local` is off by default (SSRF fail-closed). Turn it on (or set `GROK_WEB_FETCH_ALLOW_LOCAL=1`) and `web_fetch` may reach **explicit** loopback hosts only — private, link-local, and cloud-metadata ranges stay blocked. Resolution: TOML > env > default off.
|
||||
|
||||
`[toolset.ask_user_question]` is honored across **requirements.toml**, **managed
|
||||
config**, and **user `config.toml`**. Precedence: requirements → env
|
||||
(`GROK_ASK_USER_QUESTION_TIMEOUT_ENABLED` /
|
||||
`GROK_ASK_USER_QUESTION_TIMEOUT_SECS`) → user config → managed →
|
||||
defaults. Set `timeout_enabled = false` in your user config to disable the
|
||||
automatic questionnaire timeout for yourself; `timeout_secs` must be a
|
||||
positive integer. `timeout_enabled` can also be toggled from the settings
|
||||
pane (`/settings` → **Ask-Question timeout**, under Agent & Approval);
|
||||
changes apply to newly started sessions.
|
||||
`[toolset.ask_user_question]` is honored across **requirements.toml**, **managed config**, and your user **`config.toml`**. Precedence: requirements → env (`GROK_ASK_USER_QUESTION_TIMEOUT_ENABLED` / `GROK_ASK_USER_QUESTION_TIMEOUT_SECS`) → user config → managed → defaults. Set `timeout_enabled = false` in your user config to disable the automatic questionnaire timeout for yourself; `timeout_secs` must be a positive integer. You can also toggle `timeout_enabled` from `/settings` → **Ask-Question timeout** (under Agent & Approval); changes apply to newly started sessions.
|
||||
|
||||
### Authentication
|
||||
|
||||
See [Authentication](02-authentication.md) for full details.
|
||||
See [Authentication](02-authentication.md) for the full story.
|
||||
|
||||
```toml
|
||||
[auth]
|
||||
|
|
@ -272,7 +205,7 @@ client_id = "0oa1b2c3d4e5f6g7h8i9"
|
|||
# audience = "https://api.acme.com"
|
||||
```
|
||||
|
||||
### Custom Models
|
||||
### Custom models
|
||||
|
||||
Add custom model endpoints to use alternative providers or self-hosted models.
|
||||
|
||||
|
|
@ -281,7 +214,7 @@ Add custom model endpoints to use alternative providers or self-hosted models.
|
|||
model = "model-id" # model identifier sent to API
|
||||
base_url = "https://api.example.com/v1" # OpenAI-compatible endpoint
|
||||
name = "Display Name" # shown in model picker
|
||||
description = "Model description" # optional
|
||||
description = "Model description" # optional
|
||||
api_key = "sk-..." # API key for this provider
|
||||
env_key = "XAI_API_KEY" # env var(s) holding the API key; string or array (first set, non-empty wins)
|
||||
temperature = 0.7 # sampling temperature (0.0-2.0)
|
||||
|
|
@ -292,16 +225,16 @@ context_window = 128000 # context window size (for auto-compact)
|
|||
|
||||
Credential resolution: `api_key` > `env_key` > signed-in session token > `XAI_API_KEY`.
|
||||
|
||||
Override built-in models by using their name as the section key:
|
||||
To override a built-in model, use its name as the section key and set only the fields you need:
|
||||
|
||||
```toml
|
||||
[model.grok-build]
|
||||
api_key = "my-api-key" # only override the fields you need
|
||||
api_key = "my-api-key"
|
||||
```
|
||||
|
||||
### MCP Servers
|
||||
### MCP servers
|
||||
|
||||
Configure external tool integrations via the Model Context Protocol.
|
||||
Configure external tool integrations over the Model Context Protocol.
|
||||
|
||||
```toml
|
||||
[mcp_servers.github]
|
||||
|
|
@ -310,7 +243,7 @@ args = ["-y", "@modelcontextprotocol/server-github"]
|
|||
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }
|
||||
enabled = true # enable/disable (default: true)
|
||||
startup_timeout_sec = 30 # init timeout in seconds (default: 30)
|
||||
tool_timeout_sec = 6000 # tool call timeout in seconds (default: 6000)
|
||||
tool_timeout_sec = 6000 # tool call timeout in seconds (default: 6000)
|
||||
tool_timeouts = { create_issue = 120 } # per-tool timeout overrides
|
||||
|
||||
[mcp_servers.postgres]
|
||||
|
|
@ -322,9 +255,9 @@ url = "https://mcp.example.com/api/mcp" # HTTP/SSE transport
|
|||
headers = { "x-mcp-session-id" = "{{session_id}}" }
|
||||
```
|
||||
|
||||
MCP servers can also be configured per-project in `.grok/config.toml`. Project-scoped config contributes `[mcp_servers]`, `[plugins]`, and `[permission]` rules; other sections load only from `~/.grok/config.toml`.
|
||||
MCP servers can also be set per-project in `.grok/config.toml`. Project-scoped config contributes `[mcp_servers]`, `[plugins]`, and `[permission]` rules; every other section loads only from `~/.grok/config.toml`.
|
||||
|
||||
Priority for `[mcp_servers]` and `[plugins]`: `.grok/config.toml` (current dir) > `<repo-root>/.grok/config.toml` > `~/.grok/config.toml`. `[permission]` rules are not overridden by priority; they merge across all files with `deny` > `ask` > `allow` (see [22-permissions-and-safety.md](22-permissions-and-safety.md)).
|
||||
Priority for `[mcp_servers]` and `[plugins]`: `.grok/config.toml` (current dir) > `<repo-root>/.grok/config.toml` > `~/.grok/config.toml`. `[permission]` rules aren't overridden by priority — they merge across all files with `deny` > `ask` > `allow` (see [22-permissions-and-safety.md](22-permissions-and-safety.md)).
|
||||
|
||||
### Memory
|
||||
|
||||
|
|
@ -369,6 +302,21 @@ explore = "grok-build" # route to different models
|
|||
|
||||
To pin the model a subagent uses, set its entry under `[subagents.models]`.
|
||||
|
||||
### Goal mode and background workflows
|
||||
|
||||
`/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**.
|
||||
|
||||
```toml
|
||||
[workflows]
|
||||
enabled = true # enable background workflows (or GROK_WORKFLOWS=1)
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Each launch gets a session-unique display handle such as `deep-research-2`. That handle is what you see in the `/workflows` run dashboard and pass to `/workflow pause`, `resume`, or `stop` — the internal run IDs never surface in commands. A numbered handle isn't a reusable definition name, so the dashboard disables **save** until you pick a new unique `meta.name` and save the edited script yourself. See [Slash Commands](04-slash-commands.md) for examples.
|
||||
|
||||
### Skills
|
||||
|
||||
```toml
|
||||
|
|
@ -378,11 +326,9 @@ ignore = ["~/my-team-skills/wip"] # paths to exclude
|
|||
disabled = ["wip-skill"] # skill names to keep listed but inactive
|
||||
```
|
||||
|
||||
### Harness Compatibility
|
||||
### Harness compatibility
|
||||
|
||||
Control vendor compatibility for Cursor, Claude, and Codex. Every cell defaults to `true`; session cells remain staged/inert until the foreign-session scanner consumes them.
|
||||
|
||||
Session cells remain staged until a foreign-session scanner consumes them. Each tool requires both its `sessions` cell and corresponding `resume-claude`, `resume-codex`, or `resume-cursor` skill; a missing skill means zero foreign-session filesystem I/O.
|
||||
Control vendor compatibility for Cursor, Claude, and Codex. Every cell defaults to `true`. Session cells stay staged and inert until a foreign-session scanner consumes them, and each tool needs both its `sessions` cell and the matching `resume-claude`, `resume-codex`, or `resume-cursor` skill — a missing skill means zero foreign-session filesystem I/O.
|
||||
|
||||
```toml
|
||||
[compat.cursor]
|
||||
|
|
@ -405,19 +351,13 @@ sessions = true # staged; no scanner consumer yet
|
|||
sessions = true # staged; no scanner consumer yet
|
||||
```
|
||||
|
||||
Codex `skills`, `rules`, `agents`, `mcps`, and `hooks` cells are reserved and currently inert; they do not enable `.codex` discovery.
|
||||
Codex's `skills`, `rules`, `agents`, `mcps`, and `hooks` cells are reserved and currently inert — they do not enable `.codex` discovery.
|
||||
|
||||
For Claude and Cursor, `rules` and `agents` are independent: disabling named instruction files does not disable either the home or project rules directory, and disabling rules does not disable named files. Claude's `agents` cell gates home-level `~/.claude/` named files and project `<dir>/.claude/CLAUDE*.md`; generic top-level `Claude.md`, `CLAUDE.md`, and `CLAUDE.local.md` remain recognized. Project rule paths are scanned at every directory from the repo root to the current directory.
|
||||
For Claude and Cursor, `rules` and `agents` are independent: turning off named instruction files doesn't disable the home or project rules directory, and turning off rules doesn't disable named files. Claude's `agents` cell gates home-level `~/.claude/` named files and project `<dir>/.claude/CLAUDE*.md`; generic top-level `Claude.md`, `CLAUDE.md`, and `CLAUDE.local.md` stay recognized. Project rule paths are scanned at every directory from the repo root down to the current one.
|
||||
|
||||
Each cell can be toggled via environment variable or `config.toml`. See the
|
||||
environment-variables reference for the env var names. Resolution order:
|
||||
env var > config.toml > default (on).
|
||||
Each cell can be set via environment variable or `config.toml`; see the environment-variables reference for the names. Resolution: env var > config.toml > default (on).
|
||||
|
||||
`grok inspect` reports cells that still need session-start resolution as
|
||||
`?` until a value is available; cells with an explicit env or TOML value
|
||||
use that value. Affected discovery entries report
|
||||
`compatibilityStatus: "unresolved"` in JSON and `[compat unresolved]` in
|
||||
human output.
|
||||
`grok inspect` reports cells that still need session-start resolution as `?` until a value is available; cells with an explicit env or TOML value use that value. Affected discovery entries report `compatibilityStatus: "unresolved"` in JSON and `[compat unresolved]` in human output.
|
||||
|
||||
### Plugins
|
||||
|
||||
|
|
@ -429,9 +369,9 @@ disabled = ["user/a1b2c3d4/noisy-plugin"]
|
|||
|
||||
### Hints
|
||||
|
||||
The `[hints]` table holds small persisted UI preferences — mostly "stop asking me" opt-outs. Grok writes these for you when you pick a "don't ask again" / "reset in config.toml" option in the TUI, but you can edit or remove them by hand. Deleting a key restores the default behavior.
|
||||
`[hints]` holds small persisted UI preferences — mostly "stop asking me" opt-outs. Grok writes these for you when you pick a "don't ask again" option in the TUI, but you can edit or delete them by hand; removing a key restores the default.
|
||||
|
||||
`[hints]` is read from the **effective config merge** (same precedence as other settings): system managed → user `managed_config.toml` → user `config.toml` → user `requirements.toml` → system `requirements.toml`. Higher-priority layers override lower ones. The TUI only **writes** opt-outs to user `~/.grok/config.toml`.
|
||||
`[hints]` is read from the **effective config merge**, with the usual precedence: system managed → user `managed_config.toml` → user `config.toml` → user `requirements.toml` → system `requirements.toml`, higher layers winning. The TUI only ever **writes** opt-outs to your user `~/.grok/config.toml`.
|
||||
|
||||
```toml
|
||||
[hints]
|
||||
|
|
@ -443,17 +383,14 @@ fork_worktree_mode = "ask" # /fork worktree prompt: "ask" | "always"
|
|||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `project_picker_disabled` | bool | `false` | When `true`, skips the picker that asks you to choose a project directory on the first prompt when Grok is launched from a non-project directory (home, Desktop, Downloads, `/tmp`). Set automatically when you choose **"Don't ask me again"** in that picker. Teams can pin this in `managed_config.toml` or `requirements.toml` via `[hints] project_picker_disabled = true`. |
|
||||
| `project_picker_disabled` | bool | `false` | When `true`, skips the picker that asks you to choose a project directory on the first prompt when Grok launches from a non-project directory (home, Desktop, Downloads, `/tmp`). Set automatically when you choose **"Don't ask me again"** in that picker. Teams can pin it in `managed_config.toml` or `requirements.toml`. |
|
||||
| `memory_modal_fullscreen` | bool | `false` | Remembers whether the memory modal was last opened fullscreen. |
|
||||
| `new_session_worktree_mode` | string | `"never"` | Worktree prompt for `/new`: `ask` shows the popup, `always` creates a worktree, `never` skips it. |
|
||||
| `fork_worktree_mode` | string | `"ask"` | Worktree prompt for `/fork`: `ask`, `always`, or `never`. |
|
||||
|
||||
### Notifications
|
||||
|
||||
Send terminal notifications when the agent finishes a turn or needs
|
||||
approval. Notifications use terminal-native protocols (OSC 9, OSC 99, OSC 777,
|
||||
or BEL) and are focus-gated by default so they only fire when you are not
|
||||
looking at the terminal.
|
||||
Fire terminal notifications when the agent finishes a turn or needs approval. They use terminal-native protocols (OSC 9, OSC 99, OSC 777, or BEL) and are focus-gated by default, so they only fire when you're not looking at the terminal.
|
||||
|
||||
```toml
|
||||
[ui.notifications]
|
||||
|
|
@ -472,15 +409,15 @@ items = ["action-required", "spinner", "activity", "session-name", "grok"]
|
|||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `method` | string | `"auto"` | Notification protocol. `auto` picks the best for your terminal. |
|
||||
| `condition` | string | `"unfocused"` | When to notify: `unfocused` (only when terminal lost focus), `always`, or `never`. |
|
||||
| `idle_threshold_secs` | integer | `3` | Minimum seconds the terminal must be unfocused before a notification fires. |
|
||||
| `condition` | string | `"unfocused"` | When to notify: `unfocused` (only when the terminal lost focus), `always`, or `never`. |
|
||||
| `idle_threshold_secs` | integer | `3` | Minimum seconds unfocused before a notification fires. |
|
||||
| `events` | array | `["turn_complete", "approval_required"]` | Events that trigger notifications. Options: `turn_complete`, `approval_required`, `session_ready`, `task_complete`, `agent_error`. |
|
||||
| `sleep_prevention` | bool | `true` | Keep the display awake while the agent is working (macOS/Linux). |
|
||||
| `sleep_prevention` | bool | `true` | Keep the display awake while the agent works (macOS/Linux). |
|
||||
| `progress_bar` | bool | `true` | Show a progress indicator in the terminal tab (OSC 9;4). |
|
||||
| `title.enabled` | bool | `true` | Set the terminal title to reflect agent state. |
|
||||
| `title.items` | array | (see above) | Items shown in the title bar. Options: `action-required`, `spinner`, `activity`, `session-name`, `cwd`, `model`, `turn-timer`, `grok`. |
|
||||
|
||||
#### Terminal Support Matrix
|
||||
#### Terminal support matrix
|
||||
|
||||
| Terminal | Auto Protocol | Focus Tracking | Progress Bar |
|
||||
|----------|---------------|----------------|--------------|
|
||||
|
|
@ -496,13 +433,11 @@ items = ["action-required", "spinner", "activity", "session-name", "grok"]
|
|||
| Grok Desktop | None (native) | N/A | N/A |
|
||||
| Unknown | BEL | No | No |
|
||||
|
||||
When `method = "auto"`, Grok detects the terminal brand and selects the best
|
||||
protocol automatically. Set `method` explicitly to override auto-detection.
|
||||
With `method = "auto"`, Grok detects the terminal brand and picks the best protocol. Set `method` explicitly to override that.
|
||||
|
||||
#### Notification Hooks
|
||||
#### Notification hooks
|
||||
|
||||
Run custom commands when events occur. Hooks receive environment variables
|
||||
`$GROK_EVENT`, `$GROK_MESSAGE`, and `$GROK_SESSION_ID`.
|
||||
Run your own commands when events fire. Hooks receive `$GROK_EVENT`, `$GROK_MESSAGE`, and `$GROK_SESSION_ID` in the environment.
|
||||
|
||||
```toml
|
||||
# macOS native notification
|
||||
|
|
@ -532,48 +467,37 @@ timeout_secs = 5
|
|||
| `command` | string | (required) | Shell command to run. |
|
||||
| `events` | array | `[]` | Events that trigger this hook (empty = all events). |
|
||||
| `only_unfocused` | bool | `true` | Only fire when the terminal has lost focus. |
|
||||
| `timeout_secs` | integer | `10` | Kill the hook process after this many seconds (default: 10). |
|
||||
| `timeout_secs` | integer | `10` | Kill the hook process after this many seconds. |
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
**Notifications not working in tmux:**
|
||||
tmux blocks escape sequences by default. Enable passthrough for your terminal:
|
||||
**Notifications not working in tmux:** tmux blocks escape sequences by default, so enable passthrough:
|
||||
|
||||
```bash
|
||||
# In ~/.tmux.conf
|
||||
set -g allow-passthrough on
|
||||
```
|
||||
|
||||
Then restart tmux. If passthrough is not available (tmux < 3.3), set
|
||||
`method` explicitly to `"bel"` which works without passthrough.
|
||||
Restart tmux afterward. If passthrough isn't available (tmux < 3.3), set `method = "bel"`, which works without it.
|
||||
|
||||
**Focus tracking not working:**
|
||||
Some terminals do not report focus events. If `condition = "unfocused"` never
|
||||
fires, try `condition = "always"` as a fallback. Grok supports focus tracking
|
||||
in every detected terminal except Apple Terminal and unrecognized terminals.
|
||||
**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.
|
||||
|
||||
**Sleep prevention not taking effect:**
|
||||
On macOS, sleep prevention uses `IOPMAssertionCreateWithName` via CoreFoundation.
|
||||
On Linux, it uses `systemd-inhibit` (must be on `$PATH`). Check that the
|
||||
relevant tool is available. Sleep prevention is only active during agent turns
|
||||
and releases automatically when the turn ends.
|
||||
**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.
|
||||
|
||||
### Keyboard Shortcuts
|
||||
### Keyboard shortcuts
|
||||
|
||||
Keyboard shortcuts are **not configurable** via config files. All bindings are built in.
|
||||
See [Keyboard Shortcuts](03-keyboard-shortcuts.md) for the complete reference.
|
||||
Keyboard shortcuts are **not** configurable — all bindings are built in. See [Keyboard Shortcuts](03-keyboard-shortcuts.md) for the complete reference.
|
||||
|
||||
### Telemetry
|
||||
|
||||
Independent knobs (see [Monitoring Usage](24-monitoring-usage.md#related-settings)):
|
||||
These are independent knobs (see [Monitoring Usage](24-monitoring-usage.md#related-settings)):
|
||||
|
||||
- **`[features] telemetry`** / `GROK_TELEMETRY_ENABLED`: product analytics master switch. `/privacy` does not change it.
|
||||
- **`/privacy`** / Settings: coding data sharing (separate from telemetry).
|
||||
- **`[telemetry] trace_upload`** / `GROK_TELEMETRY_TRACE_UPLOAD`: session traces; follows telemetry when unset.
|
||||
- **`[telemetry] otel_*`** / `GROK_EXTERNAL_OTEL`: external OTEL to your collector (below).
|
||||
- **`[features] telemetry`** / `GROK_TELEMETRY_ENABLED` — the product-analytics master switch. `/privacy` doesn't change it.
|
||||
- **`/privacy`** / Settings — coding-data sharing, separate from telemetry.
|
||||
- **`[telemetry] trace_upload`** / `GROK_TELEMETRY_TRACE_UPLOAD` — session traces; follows telemetry when unset.
|
||||
- **`[telemetry] otel_*`** / `GROK_EXTERNAL_OTEL` — external OTEL to your own collector (below).
|
||||
|
||||
When telemetry is enabled, enterprises that run their own collector can redirect
|
||||
it or selectively disable parts of it under `[telemetry]`:
|
||||
When telemetry is on, enterprises running their own collector can redirect it or turn parts off under `[telemetry]`:
|
||||
|
||||
```toml
|
||||
[telemetry]
|
||||
|
|
@ -583,9 +507,9 @@ mixpanel_enabled = false # disable Mixpanel pro
|
|||
trace_upload = false # disable session/trace uploads (inherits the telemetry toggle when unset)
|
||||
```
|
||||
|
||||
Set these only to point telemetry at your own infrastructure or to turn parts of it off. The built-in endpoint and credentials are managed by Grok; leave them unset to use the defaults.
|
||||
Set these only to point telemetry at your own infrastructure or to switch parts off. The built-in endpoint and credentials are managed by Grok — leave them unset to use the defaults.
|
||||
|
||||
The same `[telemetry]` table also configures the **external OpenTelemetry stream**, an independent opt-in (it does not require the telemetry toggle above) that ships a curated, content-free usage schema to your *own* OTLP collector. Collector auth is supplied via `OTEL_EXPORTER_OTLP_HEADERS` and is never stored on disk. See [Monitoring & Usage](24-monitoring-usage.md) for the full schema, env vars, and privacy model.
|
||||
The same `[telemetry]` table also configures the **external OpenTelemetry stream**, an independent opt-in (it doesn't require the telemetry toggle above) that ships a curated, content-free usage schema to your *own* OTLP collector. Collector auth comes from `OTEL_EXPORTER_OTLP_HEADERS` and is never stored on disk. See [Monitoring & Usage](24-monitoring-usage.md) for the full schema, env vars, and privacy model.
|
||||
|
||||
```toml
|
||||
[telemetry]
|
||||
|
|
@ -598,7 +522,7 @@ otel_log_user_prompts = false # content gate (admins
|
|||
otel_log_tool_details = false # content gate (admins can pin via requirements)
|
||||
```
|
||||
|
||||
### Enterprise Deployment
|
||||
### Enterprise deployment
|
||||
|
||||
A complete config for enterprise use:
|
||||
|
||||
|
|
@ -626,11 +550,9 @@ telemetry = false
|
|||
|
||||
---
|
||||
|
||||
## pager.toml (Appearance Configuration)
|
||||
## pager.toml (appearance configuration)
|
||||
|
||||
Location: `~/.grok/pager.toml`
|
||||
|
||||
Controls the visual appearance and behavior of the TUI. Changes are applied on restart.
|
||||
Location: `~/.grok/pager.toml`. This controls the TUI's look and feel. Changes apply on restart.
|
||||
|
||||
### Terminal
|
||||
|
||||
|
|
@ -639,9 +561,9 @@ Controls the visual appearance and behavior of the TUI. Changes are applied on r
|
|||
alt_screen = "auto" # fullscreen mode: "auto", "always", "never"
|
||||
```
|
||||
|
||||
- `auto` (default): Use alternate screen when the terminal supports it
|
||||
- `always`: Always use alternate screen
|
||||
- `never`: Run inline in the terminal's main scrollback buffer
|
||||
- `auto` (default): use the alternate screen when the terminal supports it.
|
||||
- `always`: always use the alternate screen.
|
||||
- `never`: run inline in the terminal's main scrollback buffer.
|
||||
|
||||
### Animation
|
||||
|
||||
|
|
@ -660,7 +582,7 @@ mouse_hover = true # show hover highlight on the prompt widge
|
|||
show_prefix = true # show the prompt prefix character
|
||||
```
|
||||
|
||||
Compact mode is not persisted here. Control it at runtime with `[ui] compact_mode` or the `/compact-mode` command.
|
||||
Compact mode isn't persisted here — control it at runtime with `[ui] compact_mode` or the `/compact-mode` command.
|
||||
|
||||
### Scrollback
|
||||
|
||||
|
|
@ -699,15 +621,9 @@ highlight_overlays_border = false # highlight extends over selection box bor
|
|||
dim_accent = 0.5 # dimming factor for collapsed accents (0.0-1.0)
|
||||
```
|
||||
|
||||
`respect_manual_folds` is off by default; set it to `true` to opt in. When
|
||||
enabled, a block you fold by hand is pinned: streaming updates and finish
|
||||
events (such as a thinking block ending) leave its fold state alone, and
|
||||
expanding a block while follow-mode is tailing new content stops the
|
||||
auto-scroll so the view stays put. Follow resumes via `Shift+G`, `j` at the
|
||||
last entry, scrolling past the bottom, or sending a new prompt. `Shift+E`
|
||||
clears all pins; `Ctrl+E` clears pins on thinking blocks.
|
||||
`respect_manual_folds` is off by default. Turn it on and a block you fold by hand is pinned: streaming updates and finish events (a thinking block ending, say) leave its fold state alone, and expanding a block while follow-mode is tailing new content stops the auto-scroll so the view stays put. Follow resumes via `Shift+G`, `j` at the last entry, scrolling past the bottom, or sending a new prompt. `Shift+E` clears all pins; `Ctrl+E` clears pins on thinking blocks.
|
||||
|
||||
### Block Configuration
|
||||
### Block configuration
|
||||
|
||||
```toml
|
||||
[scrollback.blocks.edit]
|
||||
|
|
@ -737,9 +653,10 @@ badge_format = "default" # "default", "colon", or "comma"
|
|||
```
|
||||
|
||||
Badge format examples:
|
||||
- `default`: `2/5` -- a `done/total` progress fraction (done = completed, total = all tasks except cancelled)
|
||||
- `colon`: `[>:1 [ ]:4 ok:3 x:2]` -- icon:count
|
||||
- `comma`: `[1 >, 4 [ ], 3 ok, 2 x]` -- count icon, comma-separated
|
||||
|
||||
- `default`: `2/5` — a `done/total` progress fraction (done = completed, total = all tasks except cancelled).
|
||||
- `colon`: `[>:1 [ ]:4 ok:3 x:2]` — icon:count.
|
||||
- `comma`: `[1 >, 4 [ ], 3 ok, 2 x]` — count icon, comma-separated.
|
||||
|
||||
### Plugins
|
||||
|
||||
|
|
@ -749,9 +666,9 @@ disable_plugins = false # hide hooks/plugins UI entirely
|
|||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
## Environment variables
|
||||
|
||||
Key environment variables. See the README for the complete list.
|
||||
The key ones. See the README for the complete list.
|
||||
|
||||
### Authentication
|
||||
|
||||
|
|
@ -777,8 +694,9 @@ Key environment variables. 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_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_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 |
|
||||
| `GROK_SANDBOX` | Sandbox profile (off, workspace, devbox, read-only, strict; or a custom profile name) |
|
||||
|
||||
|
|
@ -786,8 +704,8 @@ Key environment variables. See the README for the complete list.
|
|||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `GROK_LOG_FILE` | Write logs to this file path (the value is used verbatim as the path) |
|
||||
| `RUST_LOG` | Log level filter (for example `debug`); controls the `GROK_LOG_FILE` log and headless stderr output |
|
||||
| `GROK_LOG_FILE` | Write logs to this file path (used verbatim as the path) |
|
||||
| `RUST_LOG` | Log level filter (e.g. `debug`); controls the `GROK_LOG_FILE` log and headless stderr output |
|
||||
|
||||
### Paths
|
||||
|
||||
|
|
@ -809,7 +727,7 @@ Key environment variables. See the README for the complete list.
|
|||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
## File locations
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
|
|
@ -822,7 +740,7 @@ Key environment variables. See the README for the complete list.
|
|||
| `~/.grok/plugins/` | User-scoped plugins |
|
||||
| `~/.grok/agents/` | User-scoped agent definitions |
|
||||
| `~/.grok/lsp.json` | LSP server configuration (user-scoped) |
|
||||
| `~/.grok/logs/` | Internal log files (for example `unified.jsonl`, MCP server logs) |
|
||||
| `~/.grok/logs/` | Internal log files (e.g. `unified.jsonl`, MCP server logs) |
|
||||
| `.grok/config.toml` | Project-scoped MCP servers, plugins, and permission rules |
|
||||
| `.grok/skills/` | Project-scoped skill definitions |
|
||||
| `.grok/plugins/` | Project-scoped plugins |
|
||||
|
|
@ -832,9 +750,9 @@ Key environment variables. See the README for the complete list.
|
|||
|
||||
---
|
||||
|
||||
## Project-Scoped Configuration
|
||||
## Project-scoped configuration
|
||||
|
||||
Some configuration can be set per-project by placing files in `.grok/` within your repository:
|
||||
Some settings can be set per-project by placing files in `.grok/` inside your repository:
|
||||
|
||||
| File | What it configures |
|
||||
|------|--------------------|
|
||||
|
|
@ -846,13 +764,13 @@ Some configuration can be set per-project by placing files in `.grok/` within yo
|
|||
| `.grok/sandbox.toml` | Custom sandbox profiles |
|
||||
| `AGENTS.md` | Project instructions (system prompt) |
|
||||
|
||||
Project-scoped MCP servers override global ones with the same name (full replacement, not merge).
|
||||
Project-scoped MCP servers override global ones with the same name (full replacement, not a merge).
|
||||
|
||||
---
|
||||
|
||||
## LSP Servers
|
||||
## LSP servers
|
||||
|
||||
Language servers power passive diagnostics and the optional `lsp` tool (see the [`lsp_tools`](#general-settings) feature flag). Server definitions are collected from three sources and merged by server name:
|
||||
Language servers power passive diagnostics and the optional `lsp` tool (see the [`lsp_tools`](#general-settings) feature flag). Definitions come from three sources and merge by server name:
|
||||
|
||||
| Source | Location | Scope |
|
||||
|--------|----------|-------|
|
||||
|
|
@ -860,10 +778,10 @@ Language servers power passive diagnostics and the optional `lsp` tool (see the
|
|||
| Project | `.grok/lsp.json` | Current repository |
|
||||
| Plugin | A trusted plugin's `.lsp.json` file, or an inline `lspServers` block in its `plugin.json` | Wherever the plugin is enabled |
|
||||
|
||||
When the same server name is defined by more than one source, it is resolved in this order (highest priority first):
|
||||
When the same server name comes from more than one source, it resolves highest-priority first:
|
||||
|
||||
1. **Project** -- `.grok/lsp.json`
|
||||
2. **User** -- `~/.grok/lsp.json`
|
||||
3. **Plugins** -- file-based `.lsp.json`, then inline `lspServers`, in plugin load order
|
||||
1. **Project** — `.grok/lsp.json`
|
||||
2. **User** — `~/.grok/lsp.json`
|
||||
3. **Plugins** — file-based `.lsp.json`, then inline `lspServers`, in plugin load order
|
||||
|
||||
Project and user entries replace lower-priority ones with the same name. Plugin entries only add servers whose names are not already defined by a local file, so a local `lsp.json` always wins over a plugin. Plugin LSP servers load only after the plugin is trusted (see [Plugins](09-plugins.md)).
|
||||
Project and user entries replace lower-priority ones of the same name. Plugin entries only add servers whose names aren't already defined by a local file, so a local `lsp.json` always wins over a plugin. Plugin LSP servers load only after the plugin is trusted (see [Plugins](09-plugins.md)).
|
||||
|
|
|
|||
|
|
@ -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 `/terminal-setup` 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 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).
|
||||
|
||||
### Automatic Quantization
|
||||
|
||||
|
|
|
|||
|
|
@ -199,7 +199,7 @@ The `--json` report includes the full detail for each skill: its `name`, `descri
|
|||
|
||||
## Bundled and Plugin Skills
|
||||
|
||||
Grok ships with built-in skills and extracts them to `~/.grok/skills/` on startup -- among them `/create-skill`, `/help`, and `/check-work`. Bundled skills behave like user skills, and a same-named skill in a higher-priority location (local or repo) overrides the bundled copy; `grok inspect` labels the extracted copies `bundled` so they stay distinguishable from skills you authored yourself. (A plugin skill of the same name does not override it; it stays available under its qualified `plugin:name` form.)
|
||||
Grok distributes platform skills separately from your personal skills. Bundled skills are cached under `~/.grok/bundled/skills/`; Grok never writes them into `~/.grok/skills/`. A same-named local, repo, or user skill overrides the bundled copy. `grok inspect` labels each definition by its actual source. (A plugin skill of the same name does not override a native skill; it stays available under its qualified `plugin:name` form.)
|
||||
|
||||
Skills can also come from plugins. When you install a plugin that includes skills, they appear alongside your user and project skills. `grok inspect` labels each plugin-provided skill with its source as `plugin: <name>`.
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ Grok processes the prompt, runs any necessary tools, and prints the result to st
|
|||
| `--tools <TOOLS>` | Allowlist of built-in tools (comma-separated). MCP meta-tools remain available unless denied. Headless only. |
|
||||
| `--disallowed-tools <TOOLS>` | Denylist of built-in tools to remove (comma-separated). Supports `Agent` entries. Headless only. |
|
||||
| `--max-turns <N>` | Maximum number of agentic turns before stopping. Headless only. |
|
||||
| `--reasoning-effort` / `--effort <LEVEL>` | Reasoning effort for reasoning models. Canonical levels: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (alias of `xhigh`). Also accepts per-model menu option ids (e.g. `deep` → mapped wire value), same as `/effort`. Works in TUI and headless. |
|
||||
| `--reasoning-effort` / `--effort <LEVEL>` | Reasoning effort for reasoning models. Canonical levels: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (each a distinct tier; a model only accepts the levels its menu advertises). Also accepts per-model menu option ids (e.g. `deep` → mapped wire value), same as `/effort`. Works in TUI and headless. |
|
||||
| `--permission-mode <MODE>` | Permission mode. `bypassPermissions` enables always-approve via this flag (see [22-permissions-and-safety.md](22-permissions-and-safety.md)); for deny-by-default use `defaultMode` in `.claude/settings.json`. |
|
||||
| `--allow <RULE>` | Permission allow rule with glob patterns (repeatable). Works in TUI and headless. |
|
||||
| `--deny <RULE>` | Permission deny rule with glob patterns (repeatable). Works in TUI and headless. |
|
||||
|
|
@ -43,7 +43,7 @@ Grok processes the prompt, runs any necessary tools, and prints the result to st
|
|||
| `--no-auto-update` | Disable update checks for this session |
|
||||
| `--sandbox <PROFILE>` | Sandbox profile for filesystem/network access |
|
||||
|
||||
> **Note:** `--tools`, `--disallowed-tools`, `--max-turns`, and `--agents` are headless-only flags. If used in the interactive TUI, a warning is printed and the flag is ignored. `--reasoning-effort`/`--effort`, `--permission-mode`, `--allow`, and `--deny` work in both modes. For more flags (agents, verification, worktrees), see [Additional Headless Flags](#additional-headless-flags).
|
||||
> **Note:** `--tools`, `--disallowed-tools`, `--max-turns`, and `--agents` are headless-only flags. If used in the interactive TUI, a warning is printed and the flag is ignored. `--reasoning-effort`/`--effort`, `--permission-mode`, `--allow`, and `--deny` work in both modes. For more flags (agents and worktrees), see [Additional Headless Flags](#additional-headless-flags).
|
||||
|
||||
### Tool Filtering
|
||||
|
||||
|
|
@ -575,8 +575,6 @@ These flags supplement the [Command-Line Options](#command-line-options) table a
|
|||
| `--agent <NAME>` | Agent name or definition file path |
|
||||
| `--agents <JSON>` | Inline subagent definitions as JSON |
|
||||
| `--system-prompt-override` | Override the agent's system prompt |
|
||||
| `--check` / `--self-verify` | Append verification loop (headless only) |
|
||||
| `--best-of-n <N>` | Run task N ways, pick best (headless only) |
|
||||
| `--no-plan` | Disable plan mode |
|
||||
| `--no-subagents` | Disable subagent spawning |
|
||||
| `--no-memory` | Disable cross-session memory |
|
||||
|
|
|
|||
|
|
@ -242,7 +242,7 @@ Grok Build also discovers roles from `.grok/roles/*.toml` and personas from `.gr
|
|||
|
||||
Grok Build shows running and finished work in side panes on the agent screen:
|
||||
|
||||
- Press `Ctrl+B` to toggle the tasks pane, which lists active and completed subagents and background commands with their status.
|
||||
- Press `Ctrl+G` to toggle the tasks pane, which lists active and completed subagents and background commands with their status.
|
||||
- Press `Ctrl+T` to toggle the separate todo pane.
|
||||
|
||||
To view the available agent types and personas, open the command palette with `Ctrl+P` and choose **Manage Agents** (`/config-agents`).
|
||||
|
|
@ -268,7 +268,7 @@ Press **Enter** (or Ctrl-F) on the block to open the subagent's full transcript.
|
|||
|
||||
For blocking subagents the single entry updates its bullet color when the child finishes. For background ones, a follow-up `Subagent completed/failed/cancelled in Xs: "..."` block is appended.
|
||||
|
||||
### Tasks pane (Ctrl+B)
|
||||
### Tasks pane (Ctrl+G)
|
||||
|
||||
As noted above — grouped under "Subagents", with spinners, elapsed times, and quick access to kill or inspect.
|
||||
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ Use `kill_command_or_subagent(task_id)` to terminate a running background task o
|
|||
|
||||
## Send a Running Task to the Background
|
||||
|
||||
In the interactive TUI, press `Ctrl+G` to send the running foreground command to the background. Do this when:
|
||||
In the interactive TUI, press `Ctrl+B` to send the running foreground command to the background. This is the only backgrounding shortcut. Do this when:
|
||||
|
||||
- A command takes longer than expected.
|
||||
- You want to ask the agent something else while a command runs.
|
||||
|
|
@ -175,7 +175,7 @@ Cancel a scheduled task by ID. Returns success if the task was found and removed
|
|||
|
||||
## The Tasks Pane
|
||||
|
||||
In the interactive TUI, press `Ctrl+B` to toggle the tasks pane. This pane lists, in a single view:
|
||||
In the interactive TUI, press `Ctrl+G` to toggle the tasks pane. This pane lists, in a single view:
|
||||
|
||||
- Running subagents and their progress
|
||||
- Active background tasks and their status
|
||||
|
|
@ -186,15 +186,15 @@ To toggle the prompt queue instead, press `Ctrl+;`.
|
|||
|
||||
---
|
||||
|
||||
## The Watching Status Line
|
||||
## The Still-Running Status Line
|
||||
|
||||
Whenever background work is still running while the agent looks idle — between turns, or while a turn is blocked on a user-interruptible wait — a persistent status line appears above the prompt:
|
||||
|
||||
```
|
||||
◎ watching · 1 command · 2 monitors · 1 loop · 1 subagent
|
||||
◎ 1 command · 2 monitors · 1 loop · 1 subagent still running
|
||||
```
|
||||
|
||||
It counts running background commands, monitors, scheduled `/loop` tasks, and background subagents, and updates live as each finishes. Any of them can wake the agent for a new turn (commands and subagents on completion, monitors on events, loops on their timer), so the cue stays up until nothing is left. Completions land in the transcript as a single "Task completed" chip — the transcript never repeats "N commands still running" lines.
|
||||
It counts running background commands, monitors, scheduled `/loop` tasks, and background subagents, and updates live as each finishes. Any of them can wake the agent for a new turn (commands and subagents on completion, monitors on events, loops on their timer), so the cue stays up until nothing is left. The running counts live only on this status line: completions land in the transcript as a single "Task completed" chip, and "Worked for" markers stay plain — the transcript never repeats or restates the running counts.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -33,15 +33,18 @@ tmux source-file ~/.tmux.conf
|
|||
# or detach and reattach
|
||||
```
|
||||
|
||||
### Live diagnostics inside Grok
|
||||
### Terminal diagnostics
|
||||
|
||||
Run this slash command:
|
||||
Run a read-only report from your shell without starting the TUI:
|
||||
|
||||
```
|
||||
/terminal-setup
|
||||
```bash
|
||||
grok doctor
|
||||
grok doctor --json # machine-readable report
|
||||
```
|
||||
|
||||
The command reports the terminal, multiplexer, **color level**, **available themes**, and a compact **Clipboard** status table, then lists any issues and fixes. When color is below truecolor, it explains how to unlock the truecolor-only themes (TokyoNight, RosePineMoon, OscuraMidnight) — or notes that Terminal.app is inherently 256-color. The aliases `/terminal-check` and `/terminal-info` run the same command.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -80,11 +83,11 @@ Detection has these limitations:
|
|||
|
||||
**Fix**: Apply the two settings above, then restart Grok.
|
||||
|
||||
**Verify**: Run `/terminal-setup`. Expect `color truecolor` and `themes all`. If `color` is `256` or `basic`, the issues section has the unlock fix.
|
||||
**Verify**: Run `/doctor`. Expect `color truecolor` and `themes all`. If `color` is `256` or `basic`, the issues section has the unlock fix.
|
||||
|
||||
### Problem: Clipboard problems
|
||||
|
||||
Grok writes to the clipboard through up to three routes, shown in the **Clipboard** section of `/terminal-setup`:
|
||||
Grok writes to the clipboard through up to three routes, shown in the **Clipboard** section of `/doctor`:
|
||||
|
||||
- **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`).
|
||||
|
|
@ -92,7 +95,7 @@ Grok writes to the clipboard through up to three routes, shown in the **Clipboar
|
|||
|
||||
**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`).
|
||||
|
||||
**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; `/terminal-setup` then shows `osc 52 off`. Native and tmux clipboard legs are unchanged.
|
||||
**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.
|
||||
|
||||
**Linux X11 selections**: X11 **PRIMARY** and **CLIPBOARD** are separate. Selecting text usually fills PRIMARY; an explicit Copy action fills CLIPBOARD. In Grok:
|
||||
|
||||
|
|
@ -113,6 +116,8 @@ Apple Terminal ignores OSC 52, so copying from a Grok session over SSH can't rea
|
|||
|
||||
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**.
|
||||
|
||||
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.
|
||||
|
||||
> **Warning**: `grok wrap` is **experimental** and may misbehave in some setups.
|
||||
|
||||
**iTerm2 setting**:
|
||||
|
|
@ -149,6 +154,8 @@ Zellij intercepts many Ctrl/Alt key combinations before they reach full-screen T
|
|||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Zellij recommends this approach for TUI users.
|
||||
|
||||
### Problem: `Ctrl+Enter` doesn't interject in WezTerm
|
||||
|
|
@ -167,7 +174,7 @@ config.enable_kitty_keyboard = true
|
|||
|
||||
Reload (`Cmd+Shift+R` or restart WezTerm) and restart `grok`.
|
||||
|
||||
**Verify**: Run `/terminal-setup` inside Grok. While a turn is active, you see the interject hint, and `Ctrl+Enter` interjects.
|
||||
**Verify**: Run `/doctor` inside Grok. While a turn is active, you see the interject hint, and `Ctrl+Enter` interjects.
|
||||
|
||||
**Quick workaround** (no global change):
|
||||
|
||||
|
|
@ -196,7 +203,7 @@ 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 `/terminal-setup` to confirm — the `newline` row shows
|
||||
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)
|
||||
|
|
@ -207,6 +214,15 @@ If Grok's mouse-driven scrolling stops responding and your terminal falls back t
|
|||
|
||||
**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.
|
||||
|
|
|
|||
|
|
@ -55,13 +55,10 @@ After splitting chained commands (on `&&`, `||`, `;`, and pipes), the following
|
|||
**Search and inspection:**
|
||||
- `grep`, `rg` (not `rg --pre` / `rg --pre=…`, which spawn a preprocessor per file)
|
||||
|
||||
**Build and check (read-only):**
|
||||
- `cargo check`
|
||||
|
||||
**Kubernetes (read-only):**
|
||||
- `kubectl get`, `kubectl logs`, `kubectl describe`
|
||||
|
||||
> **Note:** `tee` is not on this list because it can write its input to arbitrary files.
|
||||
> **Note:** `tee` is not on this list because it can write its input to arbitrary files. `cargo check` is not on this list because it compiles and runs `build.rs`, proc-macros, and any `build.rustc-wrapper` from the repo (in Ask mode it therefore prompts; Auto mode may still heuristic-allow `cargo` as a project code runner). `sort --compress-program=…` (including unique long-option abbreviations), `git -c` / `--config-env` overrides, and a git command whose local/worktree config installs an executable hook (`core.fsmonitor`, a `diff.*.command`/`textconv`/`external` driver, or a shell `alias.<safe-subcommand> = !…`) raise a request-level floor and prompt rather than auto-approve, unless the user granted that exact full script or YOLO is on.
|
||||
|
||||
These checks apply per segment. In a command like `ls && rm -rf /`, the `ls` segment is recognized as read-only, but the `rm` segment is not on the list. In `default` mode the `rm` segment prompts; under `dontAsk` it is denied.
|
||||
|
||||
|
|
@ -273,7 +270,7 @@ Path patterns are globs matched against the path string the tool was called with
|
|||
- Paths are matched as given, without canonicalization. Whether a path is absolute or relative depends on how the tool was invoked, so patterns intended as boundaries should cover both forms (for example both `/repo/secrets/**` and `secrets/**`).
|
||||
- `Read` rules also govern `grep` searches; `Grep(...)` rules match only grep.
|
||||
|
||||
`Read` and `Edit` deny rules additionally apply to file paths that shell commands touch (for example `cat` or `sed` on a denied path), and that shell-level check resolves symlinks. The direct `read_file`/`search_replace` tool checks do not resolve symlinks. For OS-level enforcement that covers every process, combine deny rules with the sandbox ([18-sandbox.md](18-sandbox.md)).
|
||||
`Read` and `Edit` deny rules additionally apply to file paths that shell commands touch (for example `cat` or `sed` on a denied path), including literal inline scripts passed to `bash`, `sh`, `dash`, `zsh`, or `ksh` with `-c`; that shell-level check also resolves symlinks. The direct `read_file`/`search_replace` tool checks do not resolve symlinks. For OS-level enforcement that covers every process, combine deny rules with the sandbox ([18-sandbox.md](18-sandbox.md)).
|
||||
|
||||
### MCP Rules
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ The state icon matches Grok Build's sibling views (
|
|||
A row stays in **Working** while it has live background work even if its
|
||||
turn has finished — a running background task, a `monitor`, or an active
|
||||
scheduled `/loop`. The activity line says what's running (e.g.
|
||||
`watching · 1 monitor · 2 loops`), since each can wake the agent for a
|
||||
`1 monitor · 2 loops still running`), since each can wake the agent for a
|
||||
new turn.
|
||||
|
||||
There are no inline group headers — the sort order keeps same-state
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Start here. These guides cover what you need on your first day.
|
|||
| 1 | [Getting Started](01-getting-started.md) | Installation, first launch, authentication, basic interaction, and key concepts |
|
||||
| 2 | [Authentication](02-authentication.md) | Browser login, API keys, OIDC/SSO, external auth providers, and device-code flow |
|
||||
| 3 | [Keyboard Shortcuts](03-keyboard-shortcuts.md) | Reference for every key binding and mouse action in the TUI |
|
||||
| 4 | [Slash Commands](04-slash-commands.md) | Every `/` command for sessions, models, memory, hooks, and plugins |
|
||||
| 4 | [Slash Commands](04-slash-commands.md) | Every `/` command, including goals, deep research, and workflow run management |
|
||||
| 5 | [Configuration](05-configuration.md) | `config.toml`, `pager.toml`, environment variables, and file locations |
|
||||
|
||||
---
|
||||
|
|
@ -47,7 +47,7 @@ Automate, script, and integrate Grok Build with other systems.
|
|||
| 17 | [Session Management](17-sessions.md) | Save, load, resume, rewind, compact, and the session persistence format |
|
||||
| 18 | [Sandbox Mode](18-sandbox.md) | OS-level filesystem and network isolation profiles |
|
||||
| 19 | [Plan Mode](19-plan-mode.md) | Structured planning, plan-file edits, and approval before coding |
|
||||
| 20 | [Background Tasks and Monitoring](20-background-tasks.md) | `background: true`, `/loop`, `monitor`, and `Ctrl+G` to demote |
|
||||
| 20 | [Background Tasks and Monitoring](20-background-tasks.md) | `background: true`, `/loop`, `monitor`, and `Ctrl+B` to demote |
|
||||
| 21 | [Terminal Support and Troubleshooting](21-terminal-support.md) | tmux, SSH, truecolor, clipboard, and OSC 52 |
|
||||
| 22 | [Permissions and Safety Controls](22-permissions-and-safety.md) | `dontAsk` mode, auto-approved tools, the safe-bash list, and restrictive PreToolUse hooks (such as git/gh-only) |
|
||||
| 23 | [Agent Dashboard](23-dashboard.md) | Central overview of local sessions and forks |
|
||||
|
|
|
|||
Loading…
Reference in a new issue