Configuration And Storage

This page explains where Grok Code stores things and how global and project settings combine.

The Two Main Config Files

Global Config

Default path:

~/.grok/config.toml

If GROK_HOME is set, Grok Code uses that directory instead of ~/.grok.

Project Config

Default path:

.grok/config.toml

Create it with:

grok init

Other Important Files And Directories

Global State

• runtime database: ~/.grok/runtime/state.db
• update backups: ~/.grok/backups/
• user memory file: ~/.grok/MEMORY.md
• global skills: ~/.grok/skills/
• global commands: ~/.grok/commands/

Project State

• project rules: .grok/rules.md
• local project preferences: GROK.local.md
• project commands: .grok/commands/
• project skills: .grok/skills/
• handoffs: .grok/handoff-*.md
• worktrees: .grok/worktrees/
• notepads: .grok/notepads/
• walkthrough output: .grok/walkthrough.md
• codebase maps: .grok/map/

Project Memory

Project auto-memory does not live inside your repo by default. It is stored under:

~/.grok/projects/<project-hash>/memory/

That directory holds:

• MEMORY.md
• topic files such as notes.md

What grok init Actually Creates

grok init creates a very small starter scaffold:

• .grok/config.toml
• .grok/rules.md
• GROK.local.md
• .grok/commands/review.md

It does not fully configure your project for you. Think of it as a safe starting point.

How Config Merging Works In Practice

Grok Code merges global and project config. The result is easiest to inspect with:

grok config

What Usually Feels Like A Normal Override

Project config can provide its own values for things like:

• xAI model and region
• shell path and shell env overrides
• project-specific custom instructions
• verification settings

What Gets Extended Instead Of Replaced

Project config extends the global config for:

• hooks
• commands
• MCP servers
• xAI Remote MCP servers
• agent role overrides
• index exclude patterns

What Is Intentionally Restricted

The project config cannot override the global self-update release URL.

This is a safety rule, not a bug.

What Often Surprises People

Not every boolean is a plain override. Some are combined instead.

Examples:

• some settings effectively require both global and project config to stay enabled
• some settings turn on if either global or project config enables them

Practical advice:

• do not guess
• run grok config
• verify the merged output before assuming a project override will win

Auth And Secrets

Common auth sources:

• stored local key from grok login
• XAI_API_KEY
• XAI_MANAGEMENT_API_KEY
• values written in config

Use grok whoami to confirm what Grok Code is actually using.

Permissions And Sandbox Defaults

The important user-facing values are:

• trust mode: off, limited, or full
• sandbox level: read-only, workspace-write, or full-access

Common places to change them:

• ctrl+g or /trust in the TUI
• --trust when starting Grok
• --sandbox or --full-auto on grok exec

Notification Defaults

By default, Grok Code enables:

• terminal bell notifications
• a minimum duration threshold before notifying

Desktop notifications are off by default unless you enable them.

When You Are Unsure

Use these commands:

grok config
grok whoami

Those two commands answer most config questions faster than reading the file by hand.