File Hierarchy & Inheritance

GEMINI.md is not one file — it is a cascade. Gemini CLI assembles project context from multiple locations and resolves them in a strict inheritance order. The global file at ~/.gemini/GEMINI.md sits at the base layer, applying to every project on your machine. The project-level GEMINI.md in your repository root overrides and extends the global layer. Subdirectory GEMINI.md files add further specificity — a GEMINI.md inside src/api/ applies only when working within that directory tree.

The inheritance model follows a principle of increasing specificity. Global rules set your personal defaults. Project rules establish team standards. Subdirectory rules handle module-specific conventions. When two rules conflict, the more specific file wins. If your global GEMINI.md says "use JavaScript" and your project GEMINI.md says "use TypeScript," TypeScript wins for that project. The resolution is silent — no warnings, no prompts. Understanding this cascade is the difference between a configuration that works and one that fights you.

The settings.json file at .gemini/settings.json is the companion to GEMINI.md. While GEMINI.md carries natural language instructions and project context, settings.json holds structured configuration — model selection, MCP server definitions, tool permissions, and sandbox settings. Both files follow the same scoping rules: global (~/.gemini/settings.json) and project-level (.gemini/settings.json). Think of GEMINI.md as the "what and why" and settings.json as the "how."

1. Global Layer (~/.gemini/) GEMINI.md for personal preferences (response style, verbosity, preferred languages). settings.json for default model, global MCP servers, and personal tool permissions. Applies to every project unless overridden.
2. Project Layer (.gemini/ + root) GEMINI.md at repo root for architecture, build commands, team conventions. .gemini/settings.json for project-specific model, MCP servers, and tool configuration. Check both into version control.
3. Subdirectory Layer (nested GEMINI.md) GEMINI.md files in subdirectories for module-specific rules. Useful when different parts of a monorepo have different conventions — the API module uses REST conventions while the frontend uses React patterns.