GEMINI.md — context Gemini CLI reads every time

Three sessions in, you notice you keep typing the same sentences. The test command. The folder that is generated and must not be touched. The convention nobody wrote down.

Write them down once instead.

What GEMINI.md is

A Markdown file of instructions. Gemini CLI loads the GEMINI.md files it finds, joins their contents, and sends them to the model with every prompt. You stop repeating yourself, and the model stops forgetting.

The Gemini CLI docs' own example starts like this:

# Project: My TypeScript Library

## General Instructions

- When you generate new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.

Where it is read from

Gemini CLI loads context files from three kinds of place, in this order:

1. Global: ~/.gemini/GEMINI.md in your home folder. Defaults for every project — how you like explanations, conventions you always want.
2. Workspace: GEMINI.md files in the folders you are working in and their parent folders. Project rules go here, usually in the project root.
3. Just in time: when one of its tools reads a file or folder, Gemini CLI also looks for GEMINI.md files in that folder and its ancestors, up to a trusted root. A note in src/payments/ is picked up when the work reaches src/payments/.

The footer shows how many context files are loaded, which is a quick check that yours was found. For the full picture, type:

/memory show

It prints the combined content of everything that was loaded — the actual text the model is getting.

Let it draft one

/init looks at the current folder and generates a GEMINI.md tailored to it. Use it, then read every line and cut what is not true. A confident, wrong context file is worse than none.

Large files can be split: a line such as @./docs/style-guide.md inside GEMINI.md imports that file’s content, so the root file stays a short index.

What earns a line

The test: would I otherwise say this at the start of every session?

• Commands: how to run the tests, the build, the linter.
• Boundaries: generated folders, vendored code, anything not to be edited by hand.
• Conventions you cannot see in the code: “Dates are stored as UTC strings.”

Every line goes with every prompt, so keep it short. Fifteen rules that matter beat three hundred lines of aspirations.

Write the exercise version in the terminal: the test command and one hands-off folder.

Already have an AGENTS.md?

GEMINI.md is only the default name. In settings.json, context.fileName takes a list, so Gemini CLI can read the file your other tools already use:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}