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.
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.
At start the CLI loads ~/.gemini/GEMINI.md, then searches the workspace directories and their parent directories for more GEMINI.md files.
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.
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.
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.
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 refreshafter 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 showprints 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.