google-gemini / google-gemini/gemini-cli

AGENTS.md silently not loaded — not in default context.fileName list in v0.49.0 (parity with agents.md convention)

Open Beginner friendly
#28,227 2 comments 0 reactions 0 assignees View on GitHub
area/agent effort/medium kind/bug priority/p2 status/bot-triaged
Dominant language
TypeScript
Stars
107k
Forks
14.6k
Avg merge
2d 3h
Merged PRs (30d)
45

Description

## Summary

`AGENTS.md` is not in the default context filename list in v0.49.0. It only works if the user adds `"context.fileName": ["AGENTS.md", "GEMINI.md"]` to `~/.gemini/settings.json`. This is a parity gap with the [`AGENTS.md`](https://agents.md/) convention adopted by Codex, Cursor, Claude Code, OpenCode, Kilo Code, Antigravity, and every other coding-agent CLI that lists a default context filename.

Confirmed in v0.49.0 source: [`packages/core/src/tools/memoryTool.ts`](https://github.com/google-gemini/gemini-cli/blob/v0.49.0/packages/core/src/tools/memoryTool.ts#L11):

```ts
export const DEFAULT_CONTEXT_FILENAME = 'GEMINI.md';
```

## History

- #12345 (closed 2026-05-08) requested this. Comment thread reads like it landed.
- #25205 (closed 2026-05-10) updated docs to imply `AGENTS.md` was in defaults.
- PR #24913 ("feat(core): add AGENTS.md to default context filenames") was **closed without merge** on 2026-05-12.
- Docs page [`docs/cli/gemini-md.md`](https://github.com/google-gemini/gemini-cli/blob/v0.49.0/docs/cli/gemini-md.md) at v0.49.0 still shows only `GEMINI.md` in the hierarchy.

Net result: users on Codex/Claude Code/OpenCode/Kilo workflows who already have an `AGENTS.md` at their repo root get zero context out of Gemini CLI on first run, silently. No warning, no hint.

## Repro

```bash
mkdir -p /tmp/agents-md-repro && cd $_
echo "# AGENTS.md" > AGENTS.md
echo "Use tabs, not spaces, in this project." >> AGENTS.md
gemini --prompt "What indentation should I use in this project?"
```

Expected: response references tabs from `AGENTS.md`.
Actual: response is generic; `AGENTS.md` was not loaded.

Confirmed by `/memory show` — the file is absent.

## Ask

Two options (either resolves this):

1. **Preferred** — merge the equivalent of #24913: add `AGENTS.md` to the default `getAllGeminiMdFilenames()` output. `GEMINI.md` stays first (priority-preserving). Users can drop `AGENTS.md` via `"context.fileName": ["GEMINI.md"]`.
2. **Fallback** — on session start, if a `GEMINI.md` search comes back empty but `AGENTS.md` exists at any of the same search paths, emit a one-time hint in the footer/log: `Found AGENTS.md but context.fileName does not include it. Add "AGENTS.md" to context.fileName to load it.`

Option 1 aligns Gemini CLI with the multi-agent fleet convention. Option 2 preserves current default but stops the silent-failure UX.

## Environment

- Gemini CLI v0.49.0
- Windows 11 / npm install
- Also reproducible on macOS 15 and Ubuntu 24.04 per source-code inspection

Contributor guide

Open the contributing guide

Research direction

Start in packages/core/src/tools/memoryTool.ts, inspect DEFAULT_CONTEXT_FILENAME and getAllGeminiMdFilenames(), then compare the current default ordering with the requested AGENTS.md behavior. Reproduce the issue with the provided /tmp/agents-md-repro commands and confirm completion when /memory show includes AGENTS.md while GEMINI.md remains first.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.