Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What is GEMINI.md?

GEMINI.md is the context file Gemini CLI reads to learn how you want it to work: coding style, project facts, standing instructions. The CLI looks for one in ~/.gemini for every project, in the project directory and its parents, and in directories its tools touch. It concatenates all of them and sends the result with each prompt.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

Gemini CLI gathers GEMINI.md files from your home folder, the project and its parents, and directories its tools touch, then sends them all with each prompt.~/.gemini/GEMINI.mdglobalrepo/GEMINI.mdprojectrepo/api/GEMINI.mdwhen a tool opens api/Gemini CLIconcatenates themthe modelwith every promptalwaysfound walking upjust in timememory + your prompt
  1. Run /init and Gemini CLI analyses the directory and writes a starting GEMINI.md, or create the file by hand. Commit it so teammates get the same context.

  2. At start the CLI loads ~/.gemini/GEMINI.md, then searches the workspace directories and their parent directories for more GEMINI.md files.

  3. When a tool reads a file or directory, the CLI scans that location and its ancestors up to a trusted root, so a deep GEMINI.md loads just in time.

  4. Everything found is concatenated and sent with every prompt. The footer shows how many context files are loaded, and /memory show prints the combined text.

  5. Edit a file mid-session and run /memory refresh to reload. Split long files with @other-file.md imports, or rename the file with context.fileName in settings.

Source: Gemini CLI docs: GEMINI.md context files

GEMINI.md versus CLAUDE.md and AGENTS.md

Each coding agent has a file it reads before doing anything: Claude Code has CLAUDE.md, Codex and others read AGENTS.md, Gemini CLI reads GEMINI.md. The contents are the same sort of thing, instructions you would otherwise type at the start of every session, so the idea moves across tools even though the file names don't. Gemini CLI makes the name configurable: set context.fileName in settings.json to AGENTS.md, or to a list of names, and one file can serve several agents.

What sets GEMINI.md apart is how aggressively it is gathered. It is not one file per project. The CLI builds a hierarchical memory from every matching file it can justify loading, and the footer tells you how many that was.

Example: a global file and a project file

In ~/.gemini/GEMINI.md, the things true of you everywhere:

Reply briefly. Prefer small diffs over rewrites.
Ask before adding a dependency.

In the repository root, the things true of this project:

TypeScript, 2-space indentation, strict equality only.
Interfaces start with I. Run pnpm test before claiming a fix works.
@docs/architecture.md

The last line is an import. The CLI reads docs/architecture.md into the memory in place, so a long design note can live where people maintain it instead of being pasted. Relative and absolute paths both work.

Where the files live and when they load

There are three tiers. The global file in ~/.gemini applies to every project and is the place for personal defaults. Workspace files are found by searching the configured workspace directories and their parents, so a GEMINI.md in a monorepo root is picked up from a package inside it. The third tier is just in time: when a tool opens a file or directory, the CLI scans that location and its ancestors up to a trusted root for more GEMINI.md files. A file in src/api therefore stays out of context until the agent actually works there.

All of it is concatenated and sent with every prompt. That is what makes it reliable, and also what makes length matter: a long file is paid for on every turn, not once.

Common mistakes

  • Putting personal preferences in the repository file. Reply style and tool habits belong in the global file. The project file is for facts teammates share.
  • Editing and expecting an immediate effect. The memory is loaded at start and on tool access. Run /memory refresh after changing a file.
  • Treating it as documentation. It rides along with every prompt. Keep it to what the model needs to act and import the rest with @file.md.
  • Not checking what loaded. /memory show prints exactly what the model sees. If an instruction is being ignored, start there.

FAQ

Can Gemini CLI use AGENTS.md instead of GEMINI.md?
Yes. Set context.fileName in settings.json to another name or a list of names, such as AGENTS.md and CONTEXT.md, and the CLI treats those files as its context files, with the same loading order.
How do I see which GEMINI.md content Gemini CLI loaded?
/memory show prints the full concatenated memory the model receives, /memory list prints the file paths, and the footer shows the count. After editing a file, run /memory refresh (the context-file guide calls it /memory reload) to re-scan.
Does a GEMINI.md in a subdirectory get loaded?
Yes, just in time. When a tool reads a file or directory there, the CLI scans that directory and its ancestors up to a trusted root and adds any GEMINI.md it finds. It is not in context until then.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.