GEMINI.MD VS AGENTS.MD

Gemini CLI looks for GEMINI.md by default, while most other agents read AGENTS.md. You can bridge them with a one-line import or a settings change; pick one, not both.

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

What Is the Difference Between GEMINI.md and AGENTS.md?

Last verified 2026-11-13 against the vendor documentation.

GEMINI.mdAGENTS.md
Default readerGemini CLICodex, Cursor, Windsurf, Jules, Zed, Cline and others
Also read byCopilot cloud agent, code review and CLI; ZedCopilot cloud agent, code review, CLI and VS Code chat
ImportsYes, @file.mdNo import syntax in the format
Global fileGEMINI.md in ~/.geminiVaries by tool, for example ~/.codex/AGENTS.md
Configurable nameYes, context.fileNameFixed name

Does Gemini CLI Read AGENTS.md?

Not under its default name setting. The context file name defaults to GEMINI.md, but the context.fileName property accepts a list, and the Gemini CLI documentation shows AGENTS.md in such a list. Once configured, Gemini CLI loads AGENTS.md like any context file.

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

Which Bridge Should You Pick?

  • Import (a GEMINI.md containing @./AGENTS.md): works with no settings, visible in the repository, leaves room for Gemini-only notes.
  • Setting (context.fileName): no extra file, but the behavior lives in .gemini/settings.json, which people may not notice.

2prompt's generator uses the import, because a file in the repository is easier to discover, and mentions the setting as an alternative in the file itself.

# 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.

How Do You Avoid Loading the Text Twice?

If context.fileName includes both AGENTS.md and GEMINI.md, and GEMINI.md also imports AGENTS.md, Gemini CLI reads AGENTS.md twice. Use the import with the default setting, or use the setting and delete the importing GEMINI.md.

What Belongs in the Home-Directory GEMINI.md?

Gemini CLI also loads a GEMINI.md from the .gemini folder in your home directory, for every project. That file is the right place for personal preferences, such as preferred answer length, your shell, or editor habits. It is the wrong place for project facts, because teammates never see it and the agent will apply it to unrelated repositories.

  • Personal habits: home-directory GEMINI.md.
  • Project facts and rules: AGENTS.md in the repository.
  • Gemini-only project notes: below the import in the project GEMINI.md.

Keeping these layers separate means a new contributor gets the full project instructions just by cloning, without inheriting anyone's personal setup.

How Do You Confirm Which Instructions Gemini CLI Loaded?

After any change to GEMINI.md, AGENTS.md or settings.json, run /memory reload so the CLI re-scans its context files. Then ask it to list the project rules it is following and compare the answer with AGENTS.md. If a rule appears twice, the file is being loaded through both the import and the setting. If a rule is missing, check that the file name in context.fileName matches exactly and that the import path is relative to the GEMINI.md that contains it.

Whichever bridge you choose, write it down. A one-line comment in AGENTS.md or the README that says how Gemini CLI picks up the shared file saves the next maintainer from guessing, and stops someone from adding the second bridge later and loading everything twice. The 2prompt generator includes this note in the GEMINI.md it writes, so the choice is visible in the repository itself rather than hidden in a settings file that few people open. Revisit the choice whenever Gemini CLI changes its defaults.

How Do You Migrate From GEMINI.md to AGENTS.md?

  1. Copy the shared parts of GEMINI.md into AGENTS.md.
  2. Replace GEMINI.md with the import line plus any Gemini-only notes.
  3. Add the real commands if they were missing; agents cannot verify work without them.
  4. Run /memory reload, then check the result with the linter.

More on each: GEMINI.md format and AGENTS.md format.

Frequently Asked Questions

Can GEMINI.md and AGENTS.md coexist?

Yes. The usual setup is AGENTS.md with the content and a short GEMINI.md that imports it with @./AGENTS.md. Just do not also add AGENTS.md to context.fileName, or it loads twice.

Where is the context.fileName setting?

In Gemini CLI settings.json, under the context object. In a project this is usually .gemini/settings.json. The value can be a single name or a list of names.

Does Copilot read GEMINI.md?

GitHub Copilot cloud agent, code review and the Copilot CLI read GEMINI.md along with AGENTS.md and CLAUDE.md. Copilot chat surfaces do not.

Which file should new projects start with?

Start with AGENTS.md, since more agents read it, then add the one-line GEMINI.md if anyone uses Gemini CLI. The 2prompt generator produces both.

Was this helpful?