What is GEMINI.md?

GEMINI.md is the default context file used by Gemini CLI to provide persistent instructions and project-specific context to the Gemini model.

Think of GEMINI.md as a project instruction file for Gemini CLI.

What is GEMINI.md used for?

Instead of repeating the same instructions in every prompt, developers can store them in a GEMINI.md file.

Typical instructions can include:

GEMINI.md example

# GEMINI.md

## Project Overview

This project is a web application built with
React, TypeScript and Vite.

## Development

Install dependencies:

npm install

Run development server:

npm run dev

## Coding Standards

- Use TypeScript strict mode
- Use functional React components
- Follow existing project conventions
- Keep components focused
- Avoid unnecessary dependencies

## Testing

- Add tests for new functionality
- Run tests before completing changes
- Use Vitest for unit tests

## Project Structure

/src
  /components
  /services
  /utils

/tests

## Working Guidelines

Before making changes:

1. Inspect existing code
2. Understand the current architecture
3. Reuse established patterns
4. Keep changes focused

Where does GEMINI.md go?

For project-specific instructions, a GEMINI.md file can be placed at the project level. 

my-project/
├── GEMINI.md
├── PROJECT-GOALS.md
├── README.md
├── package.json
└── src/

GEMINI.md context hierarchy

Gemini CLI supports hierarchical context. Instructions can therefore exist at different scopes, including global context and project or workspace context.

This makes it possible to keep broad preferences separate from instructions that only apply to a particular project or component.

GEMINI.md vs PROJECT-GOALS.md

File Purpose
GEMINI.md Provides instructions and context to Gemini CLI.
PROJECT-GOALS.md Documents what the project should achieve, its requirements and scope.

A useful distinction is:

GEMINI.md vs CLAUDE.md vs AGENTS.md

File Main role
GEMINI.md Project context and instructions for Gemini CLI.
CLAUDE.md Project context and instructions for Claude Code.
AGENTS.md General repository instructions for supported coding agents.
PROJECT-GOALS.md Project objectives, requirements and boundaries.

A practical project structure

my-project/
│
├── README.md
├── PROJECT-GOALS.md
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
│
└── src/
Define the destination before defining the instructions.

Use PROJECT-GOALS.md to document what your project should achieve before giving coding agents detailed implementation instructions.

Generate PROJECT-GOALS.md

Related guides