GEMINI.MD FORMAT

GEMINI.md is the context file Gemini CLI loads to learn about your project. Like CLAUDE.md it is plain Markdown with @file imports, and its file name is configurable, so it can be replaced by AGENTS.md entirely.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

What Is GEMINI.md?

GEMINI.md is the default name of Gemini CLI's context file. The CLI loads it at startup and adds it to the model's instructions, so it is where you put build commands, conventions and rules for your project. It is plain Markdown with no required structure.

Last verified 2026-11-13 against the vendor documentation. Outside Gemini CLI, GitHub Copilot's cloud agent, code review and CLI also read GEMINI.md, and Zed reads it as a last-resort file. See the compatibility table.

Which GEMINI.md Files Does Gemini CLI Load?

  • ~/.gemini/GEMINI.md in your home directory provides default instructions for all projects.
  • GEMINI.md files in your project, searched from the current directory up through its parents.
  • GEMINI.md files in subdirectories, which the CLI scans and adds when it works there.

Files are combined, with more specific files adding to or overriding broader ones. Run /memory reload to force a re-scan after editing.

How Do Imports Work in GEMINI.md?

Gemini CLI's memory import processor lets a context file pull in other Markdown with the @file.md syntax, for example @./components/instructions.md or @../shared/style-guide.md. That is how 2prompt's generated GEMINI.md works: it is one import line plus a short note.

# GEMINI.md

@./AGENTS.md

## Gemini CLI

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file.
- Alternative: delete this file and set "context": { "fileName": ["AGENTS.md"] } in .gemini/settings.json so Gemini CLI reads AGENTS.md directly.

Can Gemini CLI Read AGENTS.md Directly?

Yes, with one setting. GEMINI.md is only the default name; the context.fileName property in settings.json accepts a list of names. The Gemini CLI documentation shows a list that includes AGENTS.md:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}
  1. Create or open .gemini/settings.json in the project.
  2. Add the context.fileName list with AGENTS.md first.
  3. Delete GEMINI.md if it only imported AGENTS.md, so the text is not loaded twice.
  4. Run /memory reload and ask the CLI to summarize its instructions to confirm.

How Long Should GEMINI.md Be?

Gemini CLI does not publish a hard line limit for GEMINI.md that we verified, so follow the same rule as every context file: everything in it is sent on every turn. Keep it to the commands, constraints and rules the model actually needs, and import longer reference material only where it is always relevant.

How Should a Team Roll Out GEMINI.md?

Treat the context file like any other shared configuration. A personal GEMINI.md in your home directory is the place for your own habits, such as how terse you like answers or which shell you use. The project file is for facts every contributor needs: commands, layout, constraints and rules that a reviewer would enforce anyway.

  • Commit the project file and review changes to it in pull requests, the same way you review code.
  • Keep machine-specific paths and personal preferences in the home-directory file.
  • When a rule causes a bad result, fix the rule in the shared file rather than correcting the agent in every session.

If the same repository is used with Claude Code, Codex or Cursor, the shared facts belong in AGENTS.md and GEMINI.md becomes the one-line bridge described above. That way a single edit reaches every tool, and the Gemini-specific file only holds what is genuinely specific to Gemini CLI.

What Are the Common GEMINI.md Mistakes?

  • Keeping a full copy of AGENTS.md in GEMINI.md, then updating only one of them.
  • Setting context.fileName to include AGENTS.md while GEMINI.md also imports it, which loads the text twice.
  • Forgetting /memory reload after editing, then assuming the change had no effect.
  • Putting machine-specific paths in the committed file instead of the home-directory GEMINI.md.

The 2prompt generator writes the thin GEMINI.md above alongside AGENTS.md. Read GEMINI.md vs AGENTS.md for the trade-offs, and check any file with the linter.

Frequently Asked Questions

What is the default context file name in Gemini CLI?

GEMINI.md. The name is configurable through the context.fileName property in settings.json, which accepts a list of names such as AGENTS.md, CONTEXT.md and GEMINI.md.

Does Gemini CLI support imports?

Yes. Its memory import processor lets a context file import other Markdown files using the @file.md syntax with relative paths, so GEMINI.md can be a single line that imports AGENTS.md.

Should I keep GEMINI.md if I use AGENTS.md?

Either keep a one-line GEMINI.md that imports AGENTS.md, or remove it and list AGENTS.md in context.fileName. Both give Gemini CLI the shared instructions; just do not do both at once.

Does Jules read GEMINI.md?

We could not verify Jules details from its documentation on 2026-11-13. The agents.md site lists Jules as an AGENTS.md reader, so AGENTS.md is the safer file to rely on. Check the Jules documentation for current behavior.

Was this helpful?