Does Gemini CLI read AGENTS.md? What loads, in what order, and how to check

AGENTS.md is the instruction file many coding agents read from a repository root; Gemini CLI does not read it by default. At v0.65.0 the only built-in context filename is GEMINI.md; AGENTS.md is loaded only when you add it to context.fileName in settings.

A context file in Gemini CLI is a Markdown file whose text is read at startup and placed in the prompt, so a rule about tests, style, or a forbidden command does not have to be repeated in every message. The CLI calls the whole set "hierarchical memory", which is also the name used by the /memory command. It is not a database and it is not saved chat history.

The short answer:

• No, not by default. GEMINI.md is the name the CLI looks for.
• Yes, if you configure it. Add AGENTS.md to context.fileName.
• Adding it does not replace GEMINI.md. At v0.65.0 the configured names are added to the default, so a repository with both files sends both.
• The answer is version-specific. Run gemini --version first; this page describes v0.65.0, the stable release on 20 October 2026.

Checked against Gemini CLI's documentation on 27 October 2026, and against the v0.65.0 tag, commit 6006c14, of the source.

Status, 27 October 2026: the request to add AGENTS.md to the default list was closed as not planned (#12345, closed 8 May 2026). The GEMINI.md documentation says GEMINI.md is the default and mentions AGENTS.md only inside the context.fileName example, but the code starts from the configured names and keeps the current default as well (the memoryTool.ts source). Unpaid-tier and Google One users were moved to Antigravity CLI on 18 June 2026, so this page applies to paid, API-key, Vertex AI and enterprise installs; the Gemini CLI hub has the details.

Four startup sources, plus just-in-time files#

Gemini CLI reads context from more than one place. They do not all arrive at the same moment, and they are not all visible in the same check.

The first four are discovered when the session starts (and again on /memory reload). JIT files are discovered during the session, which is why /memory show can look complete while a nested rule has not arrived yet: no tool has touched its directory.

Global context and private memory go into the system instruction. Extension and workspace context go into the first user message inside <loaded_context>, under <extension_context> and <project_context> (the config.ts source). Every file is wrapped in a --- Context from: <path> --- block, so the model sees the path as well as the text.

The load order inside a repository#

Workspace discovery starts at each workspace directory and walks upward to the first directory containing a boundary marker. The marker is .git by default, configurable with context.memoryBoundaryMarkers. It collects every matching filename in each directory on that path and concatenates them from the root down.

Take this tree:

repo/                    # Git root
  GEMINI.md              # project-wide rules
  services/
    GEMINI.md            # rules for all services
    payments/
      GEMINI.md          # rules for payments only

Start Gemini CLI at repo/ and the workspace tier loads repo/GEMINI.md only; your global ~/.gemini/GEMINI.md still loads separately. The services/ and payments/ files are below your starting point, so they wait for a tool to touch those directories. Start in repo/services/payments and the workspace tier loads all three, in the order repo, services, payments. Start in a sibling directory and the payments file is not on the path at all.

A few consequences follow from that walk:

• A workspace file above the Git root is not loaded. The upward walk stops at the first .git. A nested repository or submodule with its own .git becomes the ceiling when you start inside it, so a GEMINI.md in the parent repository is out of scope.
• Without a Git root, only the starting directory is scanned. The CLI does not walk to your home directory or to a folder above the project. If the file lives one level up in a plain directory, it will not be found.
• A file in a project's .gemini/ directory is not a context file. Project context files sit in the project directories themselves. ~/.gemini/GEMINI.md is the global exception, because that is the documented global location.
• Filenames are case-sensitive on Linux. agents.md and AGENTS.md are different names. They are the same file only on a case-insensitive filesystem, and the loader deduplicates by file identity there (the memoryDiscovery.ts source).

Adding AGENTS.md without losing GEMINI.md#

Set the name in the user settings file, the project settings file, or through /settings:

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

The value can be a string or an array. The CLI then looks for AGENTS.md as well as GEMINI.md. At v0.65.0 the resulting list is AGENTS.md first, then GEMINI.md: setGeminiMdFilename starts from the configured names and then adds the current defaults, so GEMINI.md is appended after AGENTS.md. If both files exist in the same directory, both are read and both blocks are sent. This is not a replacement, and there is no setting in this version that removes GEMINI.md from the list.

What that means in practice:

• A repo with both files sends both. If they disagree, the prompt tells the model that project context outranks extension and global context, but it does not give a separate rule for two project files that contradict each other (the snippets.ts source). Delete one, or make the scopes explicit.
• Your global ~/.gemini/GEMINI.md still loads. Adding AGENTS.md to the project does not replace your global file. If you want the global rules in AGENTS.md, put that file in ~/.gemini and add the name; the loader checks the same list there.
• Project settings override user settings for the key. If a project .gemini/settings.json sets context.fileName, that array replaces the user array rather than merging with it. The built-in GEMINI.md is then added back.

The configuration reference lists context.fileName, context.memoryBoundaryMarkers, and the trust-related settings. It does not describe the merge behaviour; the source does.

Why AGENTS.md never loaded#

If /memory list does not show the file, the cause is usually one of these.

• The name is not in the effective context.fileName. Check the user file and the project file. A project value replaces the user value; neither is merged with the other before the loader adds the default.
• The setting is in a project file that is not being read. If folder trust is on and the folder is untrusted, the project .gemini/settings.json is skipped and the workspace context tier is skipped with it. Global, extension, and private project memory still load; the workspace GEMINI.md files and project settings do not (the memory context manager source). The trusted folders page describes the safe mode, and /permissions reopens the dialog.
• The file is in a sibling subtree, or below your starting directory. Discovery walks upward from where you started, not down into every directory. Start in the subtree, or let a tool touch it so JIT discovery runs. JIT content does not appear in /memory show; after the tool runs, check the tool output or /memory list.
• You edited settings during the session. The filename list is built when the CLI starts. /memory reload re-reads the files in the current list; it does not pick up a new name from settings.json. Restart Gemini CLI after changing context.fileName.
• An import is missing. A rule in a file imported with @./rules.md is expanded into the parent's block at load time. /memory list shows the parent, not the import. If the import path is wrong, the rule is absent even though the parent loaded. Imports are limited to five levels by default and circular imports are skipped (import processor).

Prove what loaded#

The checks are in the CLI, not in the model's answer. A model sees the concatenated text, not the loader's file list, and it will often say it read your file because the question suggests it did.

/memory list prints the paths of the context files in use for the session:

There are 3 GEMINI.md file(s) in use:

/home/you/.gemini/GEMINI.md
/home/you/project/GEMINI.md
/home/you/project/services/GEMINI.md

The label says "GEMINI.md" even when the list contains AGENTS.md. That is the command's fixed wording, not a sign that your setting was ignored (the commands/memory.ts source).

/memory show prints the contents, grouped as Global, Private Project Memory, Extension, and Project, with a --- Context from: <path> --- marker around each file. This is the view that proves the text reached the prompt. It does not include JIT files. Those are appended to the tool output that triggered them, under --- Newly Discovered Project Context ---, and they appear in /memory list after the tool runs.

The context summary above the input shows the count, for example 3 GEMINI.md files. The docs call it the footer; in the current UI it is the summary line above the prompt. It is hidden when ui.hideContextSummary is true (settings reference). A count is a hint, not a file list.

A marker test is the clearest check:

1. Put a unique line in the global file, the repository file, and a nested file, for example CONTEXT-MARKER-GLOBAL.
2. Start a new session and run /memory show. The global and repository markers should be there. The nested marker should not be, unless you started inside that directory.
3. Ask Gemini CLI to read a file in the nested directory. The nested context is appended to the tool result under --- Newly Discovered Project Context ---, not to the Project section; /memory list now shows the path.
4. If a marker is absent everywhere and the file exists, the file never loaded. If the marker is present and the rule is still ignored, the problem is adherence, not loading.

Do not use "ask the model to quote the file" as the only check. It can quote text that is in the context and still fail to follow the rule, and it can paraphrase a file it never received.

It loaded, but the rule is still not followed#

A context file is guidance in a prompt, not an enforcement layer. It competes with the system prompt, with other context files, and with a long conversation. Negative rules ("never commit", "do not run") are especially weak, and a long file dilutes the rules that matter.

Status, 27 October 2026: an open report on 0.18.0 describes non-trivial GEMINI.md instructions being ignored while a trivial instruction still works (#13852, open, updated 24 September 2026). Negative rules are the recurring example.

Three things help:

• Make the rule checkable and close to the work. "Run pnpm test before every commit" is easier to apply than "write clean code". Put a service-specific rule in that service's GEMINI.md.
• Re-state the rule after a long session. Compaction can replace the first user message that carried the project block with a summary: Gemini's /compress replaces the entire chat context with a summary. The compaction guide explains the general mechanism.
• Use the enforcement layer for rules that must hold. A permission rule or a policy can deny a tool call; a hook can block or inspect an action. The permissions guide and the hooks guide cover the Gemini paths.

The general split between "never loaded" and "loaded but not followed" is the same on other agents. The Claude Code page on a loaded but ignored CLAUDE.md walks through it; the Gemini-specific enforcement is in the two guides above.

Where to go next#

• Gemini CLI guides — the rest of the set: sessions, permissions, memory, MCP, models, skills, and hooks.
• What memory shows in Gemini CLI — where saved memories go, and why /memory is not a memory database.
• Context compaction — when a rule loaded at the start fades later in the session.
• Why Gemini CLI keeps asking for permission — when a rule needs to be enforced rather than requested.
• One AGENTS.md for every coding agent and the size limits by agent — the shared-file setup, and which agents cut a file and where.