Where Gemini CLI stores GEMINI.md, settings, commands, and MCP servers

Gemini CLI (Google’s open-source terminal agent) keeps its context in a global ~/.gemini/ folder, per-project .gemini/ folders, and GEMINI.md files scattered through your repos. Its one structural quirk: there is no separate MCP config file — MCP servers live inside settings.json. ~ is your home directory; paths starting with .gemini/ are relative to a project root.

At a glance

Artifact	Global	Per-project	Format
Context files (rules)	~/.gemini/GEMINI.md	GEMINI.md (root, ancestors, and subdirectories)	Markdown
Settings	~/.gemini/settings.json	.gemini/settings.json	JSON
MCP servers	~/.gemini/settings.json → mcpServers	.gemini/settings.json → mcpServers	JSON (inside settings)
Custom commands	~/.gemini/commands/**/*.toml	.gemini/commands/**/*.toml	TOML
Extensions	~/.gemini/extensions/<name>/gemini-extension.json	—	JSON + bundled files
System settings	/etc/gemini-cli/settings.json (Linux), C:\ProgramData\gemini-cli\settings.json (Windows), /Library/Application Support/GeminiCli/settings.json (macOS)	—	JSON

GEMINI.md context files

Gemini CLI concatenates context from a documented hierarchy: the global ~/.gemini/GEMINI.md, then GEMINI.md files from your working directory up through each parent to the project root (a .git folder) or home, then any in subdirectories below you (scanned up to 200 directories by default). Closer files come later, so they effectively refine the broader ones. Context files can pull in others with @path/to/file.md imports, and /memory show prints exactly what got loaded.

GEMINI.md is only the default name

The context.fileName setting accepts a string or an array — a team can set ["CONTEXT.md", "GEMINI.md"] or point it at AGENTS.md to share one rules file with Codex and Cursor. Any scanner (or teammate) looking only for files literally named GEMINI.md will miss a renamed context file entirely.

settings.json — four layers, surprising precedence

Settings merge from system defaults → user (~/.gemini/settings.json) → project (.gemini/settings.json) → system override (/etc/gemini-cli/ settings.json on Linux, C:\ProgramData\gemini-cli\settings.json on Windows, /Library/Application Support/GeminiCli/settings.json on macOS).

The system file overrides your project file

Unlike most tools, where “closest wins”, Gemini CLI’s system settings file has the highest precedence — it’s designed for administrators to enforce policy. If a setting refuses to stick on a managed machine, check /etc/gemini-cli/ (or C:\ProgramData\gemini-cli\) before debugging your own files.

String values in settings can reference environment variables ("apiKey": "$MY_TOKEN"), and the CLI auto-loads .env files — from the current directory upward, then ~/.env — so secrets tend to live one hop away from the config that names them.

MCP servers

MCP servers are a mcpServers map inside settings.json — there is no .gemini/mcp.json. Entries carry command/args/env/cwd for stdio servers or url/httpUrl/headers for remote ones, plus trust, includeTools, and excludeTools. Setting trust: true skips tool-call confirmations for that server, so it deserves the same review as an always-allow permission. The env and headers blocks are where API keys end up — treat both settings files as secret-adjacent.

Custom commands

Commands are TOML files, not Markdown: ~/.gemini/commands/ (all projects) or .gemini/commands/ (one project), each file with a required prompt field and optional description. Subdirectories namespace the name — commands/git/commit.toml becomes /git:commit — and a project command shadows a global one with the same name.

Extensions

Installed extensions live under ~/.gemini/extensions/<name>/, each with a gemini-extension.json manifest. An extension can bundle its own MCP servers (mcpServers), its own context file (contextFileName, defaulting to a GEMINI.md in the extension folder), and its own commands/ directory of TOML commands — all loaded at startup. That makes extensions a capability surface that never appears in your settings files: servers and rules you didn’t write are running from a folder most people never open.

Seeing all of it at once

Quartermaster’s scanner indexes every location on this page — including extension bundles under ~/.gemini/extensions/ and one record per MCP server parsed out of settings.json — into one searchable registry alongside Claude Code, Cursor, Codex, and 8 more tools. It can convert a GEMINI.md to CLAUDE.md or AGENTS.md (and back), and secrets are never indexed — env/header key names kept, values dropped. See the full discovery map or the quickstart.