Configuration

Grok reads configuration from two files, environment variables, and remote settings. This document covers the common options.

Precedence

Configuration is resolved in this order (highest priority first):

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. Remote settings (managed deployment via GrowthBook)
5. 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

[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

[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

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

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.

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

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.

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.

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.web_fetch]
proxy_endpoint = "https://proxy.example.com"   # egress proxy URL
allowed_domains = ["docs.rs", "x.ai"]           # override the built-in allowlist

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 = "OPENAI_API_KEY"            # env var holding the API key
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: .grok/config.toml (current dir) > <repo-root>/.grok/config.toml > ~/.grok/config.toml.

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-beta-3-small"      # embedding model
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

Harness Compatibility

Control whether Grok scans Cursor (.cursor/) and Claude (.claude/) config directories for skills, rules, project instructions, MCP servers, and hooks. All cells default to true (on), preserving existing behavior.

[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

[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

Each cell can also be toggled via environment variable (highest precedence) or remote feature flag (lowest). See the environment-variables reference for the env var names. Resolution order: env var > config.toml > feature flag > default (on).

Use grok inspect to see the resolved harness compatibility state and which entries come from which vendor. Disabled entries show [disabled] tags.

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
worktree_tip_dismissed = false         # hide the one-time worktree tip
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"

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"]

Terminal Support Matrix

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

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 it
• always: Always use alternate screen
• never: 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            # start expanded (show diff)
dual_line_numbers = false             # two-column line numbers (old + new)
line_summary = false                  # show +N/-M in header
hunk_separator = "…"                  # separator between diff hunks (default: "…")

[scrollback.blocks.prompt]
vpad = true                           # vertical padding
invert = false                        # inverted style
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: [1 2 3 4] -- colored numbers only
• colon: [>:1 [ ]:4 ok:3 x:2] -- icon:count
• comma: [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

Endpoints

Features

Logging

Paths

Telemetry

File Locations

Project-Scoped Configuration

Some configuration can be set per-project by placing files in .grok/ within your repository:

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:

When the same server name is defined by more than one source, it is resolved in this order (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

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

Copyright xAI. All rights reserved.