GEMINI.md: how Gemini CLI's context file works, with a template

What is GEMINI.md?

GEMINI.md is the Markdown file Gemini CLI loads as instructions for every prompt: project rules, code style, build and test commands, or a persona. Per the GEMINI.md docs, the CLI finds all context files in several locations, concatenates them, and sends them to the model with every prompt.

There is no required structure and no frontmatter. Write plain Markdown headings and bullet points. The footer of the Gemini CLI interface shows how many context files are loaded, which is a quick way to confirm yours was picked up.

The quickest start is /init. Per the commands reference, it "analyzes the current directory and generates a tailored context file." Edit the result down to rules you actually want enforced.

Where does Gemini CLI look for GEMINI.md?

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

The upward search stops at a boundary. In the configuration reference, context.memoryBoundaryMarkers defaults to [".git"], so traversal stops at your repo root. The same reference also describes scanning subfolders below the working directory, limited to 200 folders by default and adjustable with context.discoveryMaxDirs.

A typical layout:

~/.gemini/GEMINI.md        always use strict typing; be concise
my-repo/GEMINI.md          React + Vite, Tailwind only, Vitest for tests
my-repo/server/GEMINI.md   Python 3.11, run pytest before finishing

Content from more specific files is added after the general ones. /memory show prints the exact combined text, so you can check the order rather than guess.

What should you put in GEMINI.md?

Instructions the agent can act on. Here is a starting template adapted from the structure in Google's docs:

# Project: Acme web app

## Commands
- Install: npm install
- Dev server: npm run dev
- Tests: npm test (run before saying a task is done)

## Code style
- TypeScript strict mode. No `any`.
- 2-space indentation, single quotes.
- Use the existing `fetchWithRetry` helper for all GET requests.

## Rules
- Do not add new dependencies without saying why.
- Do not edit files in `generated/`.
- Keep components small; one component per file.

Google's memory management tutorial gives three best practices: keep it focused, use negative constraints (explicitly saying what not to do "is often more effective than vague positive instructions"), and review the file often to remove outdated rules.

How do imports work in GEMINI.md?

Large files can be split up with @ imports. A line with @ followed by a path pulls that file in:

# Main GEMINI.md

@./docs/agent/commands.md
@./docs/agent/style.md
@../shared/team-rules.md

The Memory Import Processor reference adds the details:

• Relative paths (@./file.md, @../file.md) and absolute paths (@/path/to/file.md) both work.
• Imported files can import other files. Nesting has a configurable maximum depth, 5 levels by default.
• Circular imports are detected and prevented.
• A missing file fails gracefully, leaving an error comment in the output.
• @ inside code blocks and inline code is ignored, so code examples stay literal.
• Imports are only allowed from permitted directories, which blocks reaching sensitive files outside the allowed scope.

Which /memory commands manage context?

After changing a context file mid-session, run /memory reload so the model gets the new content.

You can also add memories by asking. Tell the agent "Remember that I prefer const over let" and it edits a memory file. According to the memory tool docs, shared project instructions go into the repo's GEMINI.md, private project notes go into a per-project private memory folder, and personal preferences for all projects go into ~/.gemini/GEMINI.md. Check the diff before committing, since a remembered fact can land in a file your team shares.

Auto Memory is a separate, experimental feature. When you turn on experimental.autoMemory in settings.json, it reviews past sessions and proposes memory updates and draft skills, which you approve from /memory inbox. Nothing is applied without your approval.

How do you make Gemini CLI read AGENTS.md?

By default Gemini CLI only looks for GEMINI.md. The context.fileName setting accepts a single name or a list:

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

Put that in .gemini/settings.json to apply it to one repo, or in ~/.gemini/settings.json for every project. With it, an existing AGENTS.md works in Gemini CLI with no copy. The alternative is a one-line GEMINI.md that imports it:

@./AGENTS.md

Extensions follow the same idea: a GEMINI.md in an extension's folder is loaded automatically, and the contextFileName field in gemini-extension.json can point to a different file name.

How does GEMINI.md compare to AGENTS.md and CLAUDE.md?

The three files do the same job for different tools. If you use more than one agent, the question is which file is the source of truth.

Sources: Gemini CLI, Claude Code memory docs, Codex AGENTS.md docs.

A few details behind that table:

• Claude Code reads AGENTS.md directly only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. Otherwise it reads CLAUDE.md only, which can import AGENTS.md with @AGENTS.md. See the CLAUDE.md guide.
• Codex reads AGENTS.override.md or AGENTS.md from ~/.codex and from each folder between the repo root and your working directory, and project_doc_fallback_filenames in its config lets you list other file names. See the AGENTS.md guide.
• Gemini CLI needs context.fileName or an import to read AGENTS.md.

The low-maintenance setup for a multi-agent repo: write shared rules once in AGENTS.md, add "fileName": ["AGENTS.md", "GEMINI.md"] to .gemini/settings.json, and keep any Gemini-only notes in a short GEMINI.md. Claude Code picks up AGENTS.md on its own if you have no CLAUDE.md, or through a CLAUDE.md that starts with @AGENTS.md.

Does GEMINI.md still work in Antigravity CLI?

Yes. Google's Antigravity CLI migration guide says the agent "continues to parse and enforce rule constraints defined inside your active directory’s GEMINI.md and AGENTS.md files," and global rules in ~/.gemini/GEMINI.md are still enforced. That matters because Google moved unpaid tier and Google One users from Gemini CLI to Antigravity CLI on 18 June 2026; see the Gemini CLI guide for who is affected.

What mistakes should you avoid?

• Too much text. Every line goes into every prompt. Keep project rules short and move rarely needed procedures into Agent Skills, which load only when a task matches.
• Secrets. Never put API keys or passwords in GEMINI.md; project files are usually committed.
• Stale context. Edits mid-session need /memory reload.
• Forgetting the global file. A rule in ~/.gemini/GEMINI.md applies everywhere. If the agent does something unexpected in one repo, check /memory show for a global rule you forgot.
• Duplicated rules. If the same rule lives in GEMINI.md, CLAUDE.md and AGENTS.md, they drift apart. Pick one source and import it.

Context files are only half of a portable setup; the other half is the prompts you reuse. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name}} blanks for the parts that change.