Where apps hide your files

Gemini CLI: settings.json, GEMINI.md and the .gemini folder

Updated 2026-10-28 · 6 min read

Gemini CLI stores its user settings, global instructions, extensions and session data in the hidden folder ~/.gemini. Here is what each file is, which ones hold secrets, and how to change an MCP server without breaking anything.

The location

~/.gemini/

Gemini CLI keeps your user-level settings in one hidden folder in your home directory. The file most people are after is:

~/.gemini/settings.json

Your global instructions file is ~/.gemini/GEMINI.md, and MCP servers are configured inside settings.json under a key called mcpServers. The folder is hidden because its name starts with a dot. In Finder press ⇧⌘G and type ~/.gemini, or open it from Terminal:

open ~/.gemini

To list names without opening anything:

ls -la ~/.gemini

What is inside the folder

This table comes from the Gemini CLI source (version 0.24.0 is installed on the Mac used for this guide, and the current source was checked too) and from that Mac's folder listing. Newer versions add files, such as projects.json, policies/ and keybindings.json.

Item	What it is
settings.json	Your user settings, including mcpServers
GEMINI.md	Global instructions loaded into every session. It may not exist until you create it
.env	Optional environment variables, such as an API key
oauth_creds.json	Saved Google sign-in tokens. On the Mac used here it is owner-only (-rw-------)
google_accounts.json	Which Google account is signed in
installation_id	A random identifier for this install
state.json	A small state file
trustedFolders.json	Folders you have chosen to trust, once you trust one
mcp-oauth-tokens.json	Tokens for MCP servers that sign in with OAuth, if you use any
commands/	Your own slash commands, as .toml files
skills/	User-level skills
extensions/	Installed extensions, each with a gemini-extension.json, plus extension-enablement.json
tmp/	Per-project working data: chat recordings, shell history, checkpoints, and a bin folder
history/	Per-project history, created when needed

Other Google tools can share the folder: the Mac used here also has an antigravity folder, which Gemini CLI's own source does not create.

Several of these hold secrets. oauth_creds.json, mcp-oauth-tokens.json and any .env file can contain tokens or keys. Do not paste them into a chat, a bug report or a public repository, and keep them out of any backup you share.

Project settings and the system files

Gemini CLI's documentation lists four settings files, applied in this order, each overriding the one before:

1. System defaults: /Library/Application Support/GeminiCli/system-defaults.json
2. Your user file: ~/.gemini/settings.json
3. A project file: .gemini/settings.json in the project's root folder
4. System settings: /Library/Application Support/GeminiCli/settings.json, which override everything else

Environment variables and command-line arguments sit above all four. The two system files exist only if an administrator creates them; the Mac used for this guide has no GeminiCli folder there. GEMINI_CLI_SYSTEM_SETTINGS_PATH and GEMINI_CLI_SYSTEM_DEFAULTS_PATH point the CLI at different system files.

For .env, the CLI loads the first one it finds. It starts in the working directory and walks up through parent folders, preferring a .gemini/.env over a plain .env in each (in trusted folders). If none turns up, it falls back to ~/.gemini/.env and finally ~/.env.

GEMINI.md: global and project

Gemini CLI loads context from files named GEMINI.md. The global one is ~/.gemini/GEMINI.md. It also reads the file in your working directory and in each parent folder up to the project root (marked by a .git folder) or your home folder, plus folders below the working directory. The context.fileName setting changes the name, for example to AGENTS.md, and /memory show prints what was loaded.

Saved memories have moved between versions. In 0.24, asking the CLI to remember something appended it to the global file under a ## Gemini Added Memories heading, so the file can appear without you creating it. The current documentation says the agent now chooses between a repository GEMINI.md, a private per-project memory folder and the global ~/.gemini/GEMINI.md.

Adding or editing an MCP server

MCP servers live in settings.json:

{
  "mcpServers": {
    "my-server": { "command": "npx", "args": ["some-mcp-package"] }
  }
}

my-server and the package are placeholders. The documentation says each server needs at least one of command, url or httpUrl. You can also add one from Terminal with gemini mcp add, which writes to the project file by default and to your user file with --scope user. gemini mcp list shows what is configured.

Before editing settings.json by hand:

1. Quit any running Gemini CLI session.
2. Copy the file: cp ~/.gemini/settings.json ~/settings.json.backup.
3. Edit it in a text editor. It must stay valid JSON, so watch for missing commas.
4. Start gemini again and run /mcp to check the server.

To restore, copy the backup over the file. env values inside mcpServers can hold API keys, so do not share the file as it is.

Chats, checkpoints and the tmp folder

Session data is under ~/.gemini/tmp/, one folder per project. How those folders are named depends on the version:

• Up to 0.28 (including 0.24 on the Mac used here): a 64-character SHA-256 hash of the project's path. To match one, hash the path yourself (no trailing slash): printf '%s' /path/to/project | shasum -a 256.
• 0.29 and later: a short name made from the project folder's name, such as my-app or my-app-1, recorded in ~/.gemini/projects.json. Old hash folders are renamed the first time you use the project.

Inside you will find a chats folder with recorded sessions, a shell_history file, and checkpoints if you use that feature. These can contain your prompts and code, so look at names and sizes, not contents. ~/.gemini/tmp/bin holds a helper binary the CLI uses (rg here), so leave it alone. Very recent versions running under the macOS sandbox (gemini --sandbox) keep this runtime data in ~/.cache/.gemini instead.

On the Mac used for this guide the whole ~/.gemini folder is about 9 MB; the recorded chats are what grows. Gemini CLI's documentation does not call tmp safe to empty. Deleting a project's chat recordings removes the saved sessions for that project, and what else the folder holds changes between versions.

Backing up or moving to a new Mac

The files that carry your setup are settings.json, GEMINI.md, and the commands, skills and extensions folders. Copy those. Do not copy oauth_creds.json; sign in again on the new Mac. If you use an API key in .env, create the file again there rather than passing it around.

Why a normal search misses these

.gemini is a hidden dot-folder, and Spotlight and Finder searches leave hidden folders out. In Terminal, ls -a ~ shows it.

Finding it again

The name settings.json is shared by many apps, so type .gemini or GEMINI.md into Everywhere instead; the folder shown beside each hit tells you which copy is global and which belongs to a project. Hidden folders in your home folder such as ~/.gemini are indexed without Full Disk Access, and ⌘T on a result opens a Terminal there. It matches names only, so it finds the file and never reads the keys inside it.

Common questions

Where is the Gemini CLI settings.json on a Mac?

In ~/.gemini/settings.json. A project can also have its own .gemini/settings.json inside the project folder, and an administrator can add system files under /Library/Application Support/GeminiCli/.

Where is GEMINI.md stored?

The global file is ~/.gemini/GEMINI.md. Gemini CLI also reads GEMINI.md files in your project, looking upward from the working directory to the project root.

Where do I add MCP servers in Gemini CLI?

In the mcpServers object of settings.json, either in ~/.gemini/settings.json for all projects or in a project's .gemini/settings.json. gemini mcp add writes the entry for you.

Why can I not see the .gemini folder in Finder?

Folders whose names start with a dot are hidden. Press ⇧⌘G and enter ~/.gemini, or press ⇧⌘. in Finder to show hidden items.