37 KiB
Configuration
Grok reads configuration from local config files, environment variables, and CLI flags. This document covers the common options.
Precedence
Configuration is resolved in this order (highest priority first):
- CLI flags (e.g.,
--yolo,--model,--sandbox) - Environment variables (e.g.,
XAI_API_KEY,GROK_MEMORY) - config.toml (
~/.grok/config.toml) - Managed / requirements config (local files your org may deploy, e.g.
managed_config.toml/requirements.toml) - Built-in defaults
config.toml (Main Configuration)
Location: ~/.grok/config.toml
If the file does not exist, Grok uses built-in defaults. Specify only the values you want to override.
General Settings
[cli]
auto_update = true # check for updates on launch
[models]
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.
# See "Custom Models" for the per-model overrides and full details.
extra_headers = { "X-Request-Tags" = "team=example,env=prod" }
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
max_retries = 8
inference_idle_timeout_secs = 600
stream_tool_calls = true
[ui]
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
remember_tool_approvals = false # show per-command "Always allow" options on permission prompts;
# grants are remembered per project (default: false); see 22-permissions-and-safety.md
show_thinking_blocks = true # show agent thinking blocks in the TUI (default: true)
group_tool_verbs = true # fold runs of read/search/list tool calls and subagent rows
# — and finished thoughts among them — into one row (default: true)
collapsed_edit_blocks = false # show edits as one-line +N/-M diffstat summaries and merge
# back-to-back same-file edits into one row, expand for the
# diffs (default: false; pager.toml [scrollback.blocks.edit]
# expanded_by_default/line_summary override its fold shape)
screen_mode = "fullscreen" # default render mode: "fullscreen" | "minimal"
# (unset → fullscreen); set via /settings → Default screen mode
[features]
telemetry = false # anonymous usage telemetry
feedback = true # feedback system (default: true)
lsp_tools = false # expose the lsp tool
codebase_indexing = true # code graph indexing
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
load_envrc = true # load .envrc environment variables
[tools]
respect_gitignore = false # default: false; set true to make every tool skip gitignored files
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.
| 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. |
To switch the prompt to vim-style editing:
[ui]
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.
simple_mode and vim_mode are independent: simple_mode changes the prompt
editor, and vim_mode changes scrollback navigation. See Keyboard Shortcuts
for the full binding reference.
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.
| Value | Preselected row |
|---|---|
always_allow_all_sessions (default) |
The "Always allow on all sessions" row. |
allow_command_always |
The "Always allow this command" row. |
allow_once |
The "Yes" / allow-once row. |
reject |
The reject row. |
[ui]
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.
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.
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).
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.
| 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). |
true |
All vim-style scrollback bindings are active, exactly as listed in Keyboard Shortcuts. |
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.
vim_mode is independent of simple_mode: vim_mode controls scrollback
navigation, while simple_mode controls editing in the prompt.
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.
| 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. |
"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. |
A CLI flag always wins over the config value for that invocation.
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).
| 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. |
invert_scroll |
false | true (false) |
Reverse vertical scroll direction ("natural" scrolling). |
[ui]
scroll_speed = 50
scroll_mode = "auto" # auto | wheel | trackpad
invert_scroll = false
# scroll_lines is unset by default: the per-terminal profile stays in charge.
# 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.
Tool Configuration
[toolset.bash]
timeout_secs = 120.0 # foreground command timeout in seconds (default: 120)
output_byte_limit = 20000 # max captured output in bytes (default: 20000)
[toolset.ask_user_question]
timeout_enabled = true # false = wait forever for answers (default: true)
timeout_secs = 1800 # seconds to wait when enabled (default: 1800 / 30 min)
[toolset.web_fetch]
proxy_endpoint = "https://proxy.example.com" # egress proxy URL
allowed_domains = ["docs.rs", "x.ai"] # override the built-in allowlist
[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.
Authentication
See Authentication for full details.
[auth]
auth_provider_command = "/usr/local/bin/my-auth-provider"
auth_provider_label = "Acme Corp"
auth_token_ttl = 3600
[grok_com_config.oidc]
issuer = "https://acme.okta.com"
client_id = "0oa1b2c3d4e5f6g7h8i9"
# scopes = ["openid", "profile", "email", "offline_access", "api:access"]
# audience = "https://api.acme.com"
Custom Models
Add custom model endpoints to use alternative providers or self-hosted models.
[model.my-model]
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
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)
top_p = 0.95 # nucleus sampling parameter
max_completion_tokens = 8192 # max tokens per response
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:
[model.grok-build]
api_key = "my-api-key" # only override the fields you need
MCP Servers
Configure external tool integrations via the Model Context Protocol.
[mcp_servers.github]
command = "npx"
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_timeouts = { create_issue = 120 } # per-tool timeout overrides
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]
[mcp_servers.my-streamable-server]
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.
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).
Memory
Persist knowledge across sessions (requires --experimental-memory or GROK_MEMORY=1).
[memory]
enabled = false # enable memory
[memory.session]
save_on_end = true # write metadata summary on session end
[memory.watcher]
enabled = true # watch memory files for external edits
[memory.search]
max_results = 6 # default number of results
min_score = 0.35 # minimum relevance score
[memory.initial_injection]
enabled = true # auto-inject memory on first turn
min_score = 0.0 # score threshold for first-turn injection
[memory.embedding]
model = "embedding-model" # embedding model name
dimensions = 1024 # vector dimensions
Subagents
[subagents]
enabled = true
[subagents.toggle]
explore = true # enable/disable specific types
plan = false
[subagents.models]
explore = "grok-build" # route to different models
To pin the model a subagent uses, set its entry under [subagents.models].
Skills
[skills]
paths = ["~/my-team-skills"] # additional directories to scan
ignore = ["~/my-team-skills/wip"] # paths to exclude
disabled = ["wip-skill"] # skill names to keep listed but inactive
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.
[compat.cursor]
skills = true # scan ~/.cursor/skills/ and <cwd>/.cursor/skills/
rules = true # scan <cwd>/.cursor/rules/
agents = true # scan ~/.cursor/ for AGENTS.md files
mcps = true # scan ~/.cursor/mcp.json and <cwd>/.cursor/mcp.json
hooks = true # scan ~/.cursor/hooks.json and <cwd>/.cursor/hooks.json
sessions = true # staged; no scanner consumer yet
[compat.claude]
skills = true # scan ~/.claude/skills/ and <cwd>/.claude/skills/
rules = true # scan <cwd>/.claude/rules/
agents = true # scan ~/.claude/ for CLAUDE.md / CLAUDE.local.md
mcps = true # scan ~/.claude.json for MCP servers
hooks = true # scan ~/.claude/settings.json for hooks
sessions = true # staged; no scanner consumer yet
[compat.codex]
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.
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).
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
[plugins]
paths = ["~/my-plugins/custom-tools"]
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] 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]
project_picker_disabled = false # skip the project-directory picker
memory_modal_fullscreen = false # remember the memory modal fullscreen state
new_session_worktree_mode = "never" # /new worktree prompt: "ask" | "always" | "never"
fork_worktree_mode = "ask" # /fork worktree prompt: "ask" | "always" | "never"
| 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. |
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.
[ui.notifications]
method = "auto" # auto|osc9|osc99|osc777|bel|none
condition = "unfocused" # unfocused|always|never
idle_threshold_secs = 3 # seconds unfocused before a notification fires
events = ["turn_complete", "approval_required"]
sleep_prevention = true # prevent display sleep during agent turns
progress_bar = true # show tab progress bar (OSC 9;4)
[ui.notifications.title]
enabled = true
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. |
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). |
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 | Auto Protocol | Focus Tracking | Progress Bar |
|---|---|---|---|
| iTerm2 | OSC 9 | Yes | Yes |
| Kitty | OSC 99 | Yes | No |
| Ghostty | OSC 777 | Yes | Yes |
| WezTerm | OSC 9 | Yes | Yes |
| Warp | OSC 9 | Yes | No |
| Alacritty | BEL | Yes | No |
| VS Code | BEL | Yes | No |
| Apple Terminal | BEL | No | No |
| VTE (GNOME Terminal) | OSC 777 | Yes | No |
| 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.
Notification Hooks
Run custom commands when events occur. Hooks receive environment variables
$GROK_EVENT, $GROK_MESSAGE, and $GROK_SESSION_ID.
# macOS native notification
[[ui.notifications.hooks]]
command = "terminal-notifier -title 'Grok' -message '$GROK_MESSAGE'"
events = ["turn_complete", "approval_required"]
only_unfocused = true
timeout_secs = 10
# Push to ntfy server
[[ui.notifications.hooks]]
command = "curl -s -d '$GROK_MESSAGE' ntfy.sh/my-grok-alerts"
events = ["turn_complete"]
only_unfocused = true
timeout_secs = 10
# Play a sound
[[ui.notifications.hooks]]
command = "afplay /System/Library/Sounds/Glass.aiff"
events = ["turn_complete"]
only_unfocused = true
timeout_secs = 5
| Hook Option | Type | Default | Description |
|---|---|---|---|
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). |
Troubleshooting
Notifications not working in tmux: tmux blocks escape sequences by default. Enable passthrough for your terminal:
# 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.
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.
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.
Keyboard Shortcuts
Keyboard shortcuts are not configurable via config files. All bindings are built in. See Keyboard Shortcuts for the complete reference.
Telemetry
The [features] telemetry toggle (in the [features] block above) is the master switch for anonymous usage telemetry. When telemetry is enabled, enterprises that run their own collector can redirect it or selectively disable parts of it under [telemetry]:
[telemetry]
events_url = "https://telemetry.your-company.com/events" # send events to your own collector
events_api_key = "your-collector-token" # auth for your collector, if required
mixpanel_enabled = false # disable Mixpanel product analytics
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.
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 for the full schema, env vars, and privacy model.
[telemetry]
otel_enabled = true # external OTEL master switch (= GROK_EXTERNAL_OTEL)
otel_metrics_exporter = "otlp" # otlp | console | none
otel_logs_exporter = "otlp" # otlp | console | none
otel_endpoint = "https://collector.corp.example:4318" # OTLP base endpoint
otel_protocol = "http/protobuf" # http/protobuf | grpc
otel_log_user_prompts = false # content gate (admins can pin via requirements)
otel_log_tool_details = false # content gate (admins can pin via requirements)
Enterprise Deployment
A complete config for enterprise use:
[cli]
auto_update = false
[auth]
auth_provider_command = "/usr/local/bin/my-company-auth-provider"
auth_provider_label = "Acme Corp"
auth_token_ttl = 3600
[models]
default = "company-grok"
[model.company-grok]
model = "grok-build"
base_url = "https://grok-proxy.acme.com/"
name = "Grok Build Latest (Proxy)"
context_window = 128000
[features]
telemetry = false
pager.toml (Appearance Configuration)
Location: ~/.grok/pager.toml
Controls the visual appearance and behavior of the TUI. Changes are applied on restart.
Terminal
[terminal]
alt_screen = "auto" # fullscreen mode: "auto", "always", "never"
auto(default): Use alternate screen when the terminal supports italways: Always use alternate screennever: Run inline in the terminal's main scrollback buffer
Animation
[animation]
fps = 30 # animation frame rate (ticks per second)
wave_rows = 32 # rows per wave cycle for accent animation
Prompt
[prompt]
collapse_unfocused = true # collapse prompt when scrollback is focused
mouse_hover = true # show hover highlight on the prompt widget
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.
Scrollback
[scrollback.layout]
outer_vpad = 1 # vertical padding
outer_hpad_left = 2 # left horizontal padding
outer_hpad_right = 2 # right horizontal padding
block_pad_left = 2 # padding inside block, left of content
block_pad_right = 2 # padding inside block, right of content
[scrollback.scrollbar]
enabled = true # show scrollbar
gap_left = 0 # gap between content and scrollbar
gap_right = 0 # gap between scrollbar and screen edge
[scrollback.scroll]
margin = 0 # minimum context lines above/below selection
min_page_fraction = 0 # minimum scroll as % of viewport (0-100)
follow_indicator = "center" # follow indicator: "center" or "none"
follow_auto_select = true # auto-select latest entry in follow mode
follow_by_overscroll = true # scrolling past bottom engages follow mode
anchor_on_fold = true # keep block position when folding
respect_manual_folds = true # opt-in (default: false): keep manually folded blocks as-is during streaming/finish; expanding while following stops auto-scroll
[scrollback.display]
sticky_headers = true # pin user prompts as sticky headers
tab_width = 4 # spaces per tab character
expandable_indicator = true # show expand indicator on foldable entries
expandable_indicator_running = true # show indicator on running entries
expandable_indicator_char = "›" # character for the expand indicator (default: "›")
selection_buttons = false # show copy/view buttons on selection
line_under_last_entry = false # horizontal line below last entry
group_selection_split = true # split selection box for expanded blocks
highlight_overlays_border = false # highlight extends over selection box border
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.
Block Configuration
[scrollback.blocks.edit]
indent = true # indent diff content
vpad = false # vertical padding
# expanded_by_default = true # unset: follows [ui] collapsed_edit_blocks in config.toml
# (flag on = collapsed one-liner); uncomment to pin either shape
dual_line_numbers = false # two-column line numbers (old + new)
# line_summary = false # show +N/-M in the collapsed header; unset follows the same flag
hunk_separator = "…" # separator between diff hunks (default: "…")
[scrollback.blocks.prompt]
vpad = true # vertical padding
show_prefix = true # show prompt prefix character
min_lines = 2 # minimum content lines in sticky mode
[scrollback.blocks.thinking]
animate = true # animated accent while thinking
truncated_lines = 3 # lines in truncated mode
Todo
[todo]
badge_format = "default" # "default", "colon", or "comma"
Badge format examples:
default:2/5-- adone/totalprogress fraction (done = completed, total = all tasks except cancelled)colon:[>:1 [ ]:4 ok:3 x:2]-- icon:countcomma:[1 >, 4 [ ], 3 ok, 2 x]-- count icon, comma-separated
Plugins
disable_plugins = false # hide hooks/plugins UI entirely
Environment Variables
Key environment variables. See the README for the complete list.
Authentication
| Variable | Description |
|---|---|
XAI_API_KEY |
API key from console.x.ai |
GROK_AUTH_PROVIDER_COMMAND |
External auth binary path |
GROK_AUTH_PROVIDER_LABEL |
Display name on TUI login screen |
GROK_AUTH_TOKEN_TTL |
Token lifetime in seconds |
GROK_AUTH_EARLY_INVALIDATION_SECS |
Seconds before expiry to refresh (default: 300) |
GROK_OIDC_ISSUER |
OIDC issuer URL |
GROK_OIDC_CLIENT_ID |
OIDC client ID |
Endpoints
| Variable | Description |
|---|---|
GROK_CLI_CHAT_PROXY_BASE_URL |
Override API proxy base URL |
Features
| Variable | Description |
|---|---|
GROK_MEMORY |
Enable (1) or disable (0) cross-session memory |
GROK_SUBAGENTS |
Enable (1) or disable (0) subagents |
GROK_WEB_FETCH |
Enable (1) or disable (0) the web_fetch tool |
GROK_AGENT |
Custom agent definition path or name |
GROK_SANDBOX |
Sandbox profile (off, workspace, devbox, read-only, strict; or a custom profile name) |
Logging
| 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 |
Paths
| Variable | Description |
|---|---|
GROK_HOME |
Override config directory (default: ~/.grok) |
GROK_RESPECT_GITIGNORE |
Force gitignore filtering on (1) or off (0); overrides [tools] respect_gitignore |
Telemetry
| Variable | Description |
|---|---|
GROK_TELEMETRY_ENABLED |
Enable/disable telemetry |
GROK_FEEDBACK_ENABLED |
Enable/disable feedback system |
GROK_DEPLOYMENT_KEY |
Management API key for enterprise |
File Locations
| Path | Description |
|---|---|
~/.grok/config.toml |
Main configuration file |
~/.grok/pager.toml |
TUI appearance configuration |
~/.grok/auth.json |
Authentication credentials (auto-managed) |
~/.grok/sessions/ |
Persisted sessions (organized by working directory) |
~/.grok/memory/ |
Cross-session memory files and index |
~/.grok/skills/ |
User-scoped skill definitions |
~/.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/config.toml |
Project-scoped MCP servers, plugins, and permission rules |
.grok/skills/ |
Project-scoped skill definitions |
.grok/plugins/ |
Project-scoped plugins |
.grok/agents/ |
Project-scoped agent definitions |
.grok/hooks/ |
Project-scoped hooks |
.grok/lsp.json |
LSP server configuration |
Project-Scoped Configuration
Some configuration can be set per-project by placing files in .grok/ within your repository:
| File | What it configures |
|---|---|
.grok/config.toml |
MCP servers, plugins, permission rules, and the [mcp] max_output_bytes tool-result cap (other sections load only from ~/.grok/config.toml) |
.grok/skills/ |
Project-specific skills |
.grok/hooks/ |
Project-specific lifecycle hooks |
.grok/agents/ |
Project-specific agent definitions |
.grok/lsp.json |
LSP server configuration |
.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).
LSP Servers
Language servers power passive diagnostics and the optional lsp tool (see the lsp_tools feature flag). Server definitions are collected from three sources and merged by server name:
| Source | Location | Scope |
|---|---|---|
| User | ~/.grok/lsp.json |
All projects |
| 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):
- Project --
.grok/lsp.json - User --
~/.grok/lsp.json - Plugins -- file-based
.lsp.json, then inlinelspServers, 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).