`gemini-md` — `GEMINI.md`¶

Summary¶

A plain Markdown file placed at the repository root that provides persistent instructional context to the Google Gemini CLI. Contents are concatenated with context files from other locations and sent to the model with every prompt. Designed to replace per-prompt repetition of project-specific instructions with a once-defined, version-controlled file.

Tool¶

Primary: Google Gemini CLI (gemini) — open-source, Apache 2.0, npm package @google/gemini-cli
No confirmed cross-tool support for .github/copilot-instructions.md-style reading. Gemini CLI can be configured to fall back to AGENTS.md via settings.json (see Alternate paths), but other tools do not natively read GEMINI.md.

Support level¶

planned — v0.2 target. Researched 2026-03-07.

Canonical path(s)¶

GEMINI.md — repository root. This is the default context filename for the project scope.
~/.gemini/GEMINI.md — user global scope (machine-local, not repo-committed; not generated by agent-policy).

Alternate / legacy path(s)¶

The GEMINI.md filename is configurable via ~/.gemini/settings.json (global) or .gemini/settings.json (project-local):

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

When fileName is an array, the CLI checks names in order and uses the first match found in each directory. This means a repo can opt in to having Gemini CLI read AGENTS.md instead of GEMINI.md — no GEMINI.md file is needed in that case.

There are no legacy deprecated path names.

File format¶

Plain Markdown. No required structure, no frontmatter. Free-form prose, headings, and bullet lists.

Vendor example (verbatim from geminicli.com/docs/cli/gemini-md/, accessed 2026-03-07):

# Project: My TypeScript Library

## General Instructions
- When you generate new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.

## Coding Style
- Use 2 spaces for indentation.
- Prefix interface names with `I` (for example, `IUserService`).
- Always use strict equality (`===` and `!==`).

No documented size limit. For context window efficiency, keep the file concise.

Frontmatter¶

None. Plain Markdown only. Frontmatter is not parsed or used by Gemini CLI for GEMINI.md.

Discovery / scope behavior¶

Gemini CLI uses a three-tier hierarchical context system. All found files are concatenated and sent with every prompt (source: geminicli.com/docs/cli/gemini-md/, accessed 2026-03-07):

Global context file
Path: ~/.gemini/GEMINI.md
Scope: applies to all projects on this machine
Not repo-committed; not generated by agent-policy
Workspace / environment context files
Path: Gemini CLI searches for GEMINI.md in the configured workspace directories and their parent directories
Scope: context for the projects currently being worked on
Just-in-time (JIT) context files
Path: when the CLI's file-access tool reads a file or directory, it automatically scans for GEMINI.md in that directory and all ancestors up to the trusted root
Scope: highly specific instructions for individual components; loaded only on demand, not at session start

The CLI footer displays the count of loaded context files as a visual indicator.

/memory command — interactive context management during a session:

Command	Effect
`/memory show`	Displays the full concatenated content of all currently loaded context files
`/memory refresh`	Forces a re-scan and reload of all `GEMINI.md` files from all locations
`/memory add <text>`	Appends the text to `~/.gemini/GEMINI.md` (the global file only)

Import syntax — a GEMINI.md file can import other Markdown files using @path syntax:

# Main GEMINI.md

Main instructions here.

@./components/component-guide.md

@../shared/style-guide.md

Both relative and absolute paths are supported. Full reference: geminicli.com/docs/reference/memport.

Repo-safe¶

Yes. GEMINI.md at the project root is designed to be version-controlled and shared with the team.

~/.gemini/GEMINI.md (the global scope file) is machine-local and must not be committed.

Renderer notes¶

Target ID: gemini-md
Output path: GEMINI.md
Template: templates/GEMINI.md.j2
OutputTargets field: gemini_md: bool
Notes: Content is structurally identical to AGENTS.md. The template can be a near-copy of AGENTS.md.j2. Keep as separate template files so they can diverge if Gemini-specific guidance is warranted in future versions. Single file output — no per-directory variants are generated.

Known limitations / gotchas¶

Configurable filename creates redundancy risk: If a user configures Gemini CLI to read AGENTS.md via settings.json, enabling both agents-md and gemini-md outputs in agent-policy.yaml will result in Gemini CLI receiving the same policy content twice (once from each file). Document this in the schema reference and getting-started guide.
JIT loading delivers context outside the root file: Component-level GEMINI.md files in subdirectories load when Gemini accesses files in those directories. agent-policy only generates the root-level file. Teams managing multi-component repos must be aware that subdirectory GEMINI.md files they create manually will be loaded.
Import chain not generated: agent-policy does not generate import-based modular context. Single-file output only.
No enforced size limit: Unlike Claude Code (200-line guideline) or Codex (32 KiB cap), Gemini CLI has no documented hard size limit. However, large files consume context tokens on every prompt; keep files concise.
Context, not enforcement: Like all tools in this ecosystem, Gemini CLI treats GEMINI.md as model context, not a hard constraint system. Instruction adherence depends on model behavior.

Official references¶

Google Gemini CLI docs — "Provide context with GEMINI.md files": https://geminicli.com/docs/cli/gemini-md/ (accessed 2026-03-07)
Google Gemini CLI npm package README (confirms canonical docs site and GEMINI.md feature): https://www.npmjs.com/package/@google/gemini-cli (accessed 2026-03-07)
Google Gemini CLI GitHub repository: https://github.com/google-gemini/gemini-cli (accessed 2026-03-07)
Memory import syntax reference: https://geminicli.com/docs/reference/memport (not fetched; confirmed from gemini-md docs page links)

Minimal example¶

# GEMINI.md

## Build and test

- Build: `cargo build --release`
- Test: `cargo test --all-targets`
- Lint: `cargo clippy --all-targets -- -D warnings`

## Coding standards

- MSRV is 1.75. Do not use APIs stabilized after 1.75.
- All public items must have rustdoc comments.
- Do not use `unwrap()` or `expect()` in library code.

## Architecture

- Business logic lives in `src/lib.rs` and submodules, not `src/main.rs`.
- All error types are defined in `src/error.rs`.
- New output targets require: a renderer in `src/render/`, a template in `templates/`, and golden tests.

## What not to do

- Do not modify `Cargo.toml` or `.github/workflows/` without human review.
- Do not commit secrets, credentials, or API keys.

Internal mapping notes¶

Target ID: gemini-md — to be added to TargetId enum in src/model/targets.rs
Output path constant: "GEMINI.md" — to be returned by TargetId::primary_path()
Template file: templates/GEMINI.md.j2 — not yet created
Golden test snapshots: not yet created
Renderer module: src/render/gemini_md.rs — not yet created
Status: planned for v0.2

gemini-md — GEMINI.md¶