Where Grok CLI stores GROK.md, settings, and MCP servers

“Grok CLI” is several projects; this page covers the dominant one: superagent-ai/grok-cli (npm grok-dev, formerly @vibe-kit/grok-cli) — the open-source terminal coding agent for xAI’s Grok API, not an official xAI product. Its file layout has churned more than any other tool here: custom instructions changed name and MCP configs changed file between 0.x and 1.x, so what’s on your disk depends on when you installed it. ~ is your home directory.

At a glance

Artifact	Global	Per-project	Format
Custom instructions (0.x)	~/.grok/GROK.md	.grok/GROK.md	Markdown
Instructions (1.x)	—	AGENTS.md (git root → cwd), AGENTS.override.md	Markdown
User settings	~/.grok/user-settings.json	—	JSON
Project settings	—	.grok/settings.json	JSON
MCP servers (0.x)	—	.grok/settings.json → mcpServers	JSON map
MCP servers (1.x)	~/.grok/user-settings.json → mcp.servers	—	JSON array

Custom instructions: GROK.md, then AGENTS.md

Through the 0.x releases, custom instructions were GROK.md — global in ~/.grok/GROK.md, per-project in .grok/GROK.md, project winning on conflict. Note the project copy lives inside .grok/, not at the repo root the way CLAUDE.md does.

GROK.md support was removed in 1.0.0-rc3

The March 2026 1.0.0-rc3 release dropped GROK.md entirely (PR #181). Current versions read AGENTS.md instead — the cross-tool convention Codex and Cursor share — merged from the git root down to your working directory, with AGENTS.override.md replacing (not merging with) the cascade for its directory. If you upgraded, a stale .grok/GROK.md sits on disk silently doing nothing; move its content to AGENTS.md.

user-settings.json

~/.grok/user-settings.json is the global config: apiKey, baseURL (default https://api.x.ai/v1 — the CLI drives any OpenAI-compatible endpoint), defaultModel, custom subAgents (name + model + instruction), hooks (lifecycle handlers like PreToolUse/PostToolUse), Telegram and sandbox settings. The apiKey field makes this file a plaintext credential store — keep it out of backups you share. GROK_API_KEY, GROK_BASE_URL, and GROK_MODEL environment variables override it for CI.

.grok/settings.json

The per-project file holds what should differ per repo: model (e.g. "grok-code-fast-1") plus sandbox/LSP options, shallow-merged over the user settings with the project winning. In 0.x it also held MCP servers — see below.

MCP servers — which file, depends on the version

Your MCP config moved between 0.x and 1.x

In 0.x, MCP servers were a name-keyed map in the project’s .grok/settings.json:

{
  "mcpServers": {
    "linear": { "name": "linear", "transport": "stdio",
                "command": "npx", "args": ["@linear/mcp-server"] }
  }
}

Current 1.x code stores them globally instead — an array under mcp.servers in ~/.grok/user-settings.json (fields: id, label, enabled, transport stdio/http/sse, command/args/env or url/headers), managed via grok mcp add ... or /mcps in the TUI. Editing an old project-level mcpServers block on a 1.x install changes nothing.

Either way, the env and headers values are where API keys end up — both files are secret-adjacent even when the rest is shareable.

Other files under .grok/

~/.grok/workspace-trust.json records per-workspace sandbox/host-mode decisions; project-side, .grok/computer/ (screenshots) and .grok/generated-media/ (image/video output) are working artifacts, not context — safe to gitignore.

Seeing all of it at once

Quartermaster’s scanner indexes both generations of this layout — GROK.md rules, .grok/settings.json and ~/.grok/user-settings.json with one record per MCP server — into one searchable registry alongside Claude Code, Cursor, Codex, and 8 more tools, and can convert a stranded GROK.md to AGENTS.md or CLAUDE.md. Secrets are never indexed — the apiKey field is never read, and env/header key names are kept while values are dropped. See the full discovery map or the quickstart.