GEMINI.md -- Project Context

Every AI coding agent has a file it reads at session start. Claude Code has CLAUDE.md. GitHub Copilot has COPILOT.md. Gemini CLI has GEMINI.md. The file sits in your project root and gives Gemini CLI persistent context about your project: the language, the build system, the conventions, the gotchas. Write it well and every session starts with the agent already oriented. Write it poorly and you spend the first five minutes of every session re-explaining your project.

What you'll learn

• GEMINI.md lives in your project root and is loaded automatically at the start of every session
• Content that belongs: language, build commands, directory structure, coding conventions, known gotchas, and links to key docs
• Content that doesn't: files you can already read (source code, lockfiles), transient state, entire READMEs
• Generate a starting point with /init, then refine by hand with the specifics only a human on the project knows
• Migration note: Antigravity CLI also reads GEMINI.md. The format is identical. If you migrate, your context file works without changes

The problem

Without a context file, every Gemini CLI session starts from zero. You explain the project structure, the build commands, the testing conventions, the known quirks -- the same preamble every time you open a REPL. With GEMINI.md, you explain it once. The agent reads it before your first prompt and already knows how the project works. The difference is the difference between onboarding a new teammate with a README versus a hallway conversation.

Options & when to use each

Approach	Good for	Costs you	When to pick it
/init generated GEMINI.md	New projects, getting started fast	Needs manual review; includes guesses that may be wrong	You're creating a new project and want a starting point in 30 seconds
Hand-written GEMINI.md	Existing projects with established conventions	Takes time to write, but pays off in every session	You know your project well and want precision
Hybrid: /init then edit	Most real projects	Same as /init plus editing time	The best of both -- get the scaffold, then fill in the specifics
No GEMINI.md	None	Every session starts cold. You re-explain the project each time	Only if the project is trivial or you never plan to open Gemini CLI in it again

Build it

Step 1: Create a sample project

We'll create a small Python project so you can see how GEMINI.md works in practice:

mkdir -p /tmp/weather-cli/src /tmp/weather-cli/tests
cd /tmp/weather-cli

cat > src/main.py << 'EOF'
"""Weather CLI -- fetch weather for any city."""
import sys
import requests

def get_weather(city: str) -> dict:
    """Fetch current weather from wttr.in."""
    url = f"https://wttr.in/{city}?format=j1"
    response = requests.get(url)
    response.raise_for_status()
    return response.json()

def main():
    if len(sys.argv) < 2:
        print("Usage: weather <city>")
        sys.exit(1)
    city = sys.argv[1]
    try:
        data = get_weather(city)
        current = data["current_condition"][0]
        print(f"{city}: {current['temp_C']}C, {current['weatherDesc'][0]['value']}")
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()
EOF

cat > tests/test_weather.py << 'EOF'
from src.main import get_weather

def test_get_weather_returns_dict():
    result = get_weather("London")
    assert isinstance(result, dict)
    assert "current_condition" in result
EOF

cat > requirements.txt << 'EOF'
requests>=2.28.0
pytest>=7.0.0
EOF

Step 2: Generate a starting GEMINI.md

Run the initialization command in your new directory. This drops you into the interactive prompt where you can configure project defaults.

cd /tmp/weather-cli
gemini

Inside the REPL:

Once the agent starts, invoke the init slash command to begin the configuration wizard.

> /init

Answer the prompts:

• Language: Python
• Build system: pip
• Testing: pytest
• Description: "A command-line weather tool that fetches current conditions from wttr.in"

Then exit and read what it generated:

cat GEMINI.md

The generated file will have a basic structure. It's a starting point. Now we'll make it actually useful.

Step 3: Write the real GEMINI.md

Replace the generated file with a hand-tuned version. Here's a template you can adapt for any project:

# Weather CLI

A command-line tool that fetches current weather conditions from wttr.in.

## Stack

- Language: Python 3.10+
- HTTP client: `requests` (no async)
- Testing: pytest with standard assertions
- No database, no async framework

## Directory structure

weather-cli/ src/ -- application code tests/ -- pytest test files GEMINI.md -- this file

## Commands

Define the common setup and execution commands for the project. These instruct the agent on how to install dependencies and run the application.

```bash
# Install dependencies
pip install -r requirements.txt

# Run the CLI
python src/main.py London

# Run tests
pytest tests/ -v

Conventions

• Type hints on all function signatures
• Docstrings use triple-quote format with a one-line summary
• Error output goes to stderr, normal output to stdout
• Test files match tests/test_*.py
• No external API keys needed -- wttr.in is open

Gotchas

• requests.get() without a timeout can hang on network issues. Always pass timeout=10
• wttr.in returns HTTP 200 even for unknown cities, with an error field in the JSON. Check for it
• The wttr.in format=j1 parameter is case-sensitive

Write this to the file (or ask Gemini CLI to do it):

```bash
gemini -p "Write a GEMINI.md for this project at /tmp/weather-cli. It's a Python CLI using requests to fetch weather from wttr.in. Pytest for testing. No async. Include: language, build commands, directory structure, coding conventions, and gotchas about requests timeouts and wttr.in behavior." --yolo

Step 4: Test that GEMINI.md is loaded

Start a fresh session and ask Gemini CLI about the project -- without re-explaining anything:

cd /tmp/weather-cli
gemini

Ask the agent how to execute the test suite to confirm it parsed the context.

> How do I run the tests in this project?

If Gemini CLI says pytest tests/ -v, it read GEMINI.md. If it says "I don't know, let me look around," the file isn't being picked up.

To verify explicitly:

You can also query the agent about specific guidelines you established. This confirms it loaded the custom conventions block.

> What does GEMINI.md say about error handling conventions?

Gemini CLI should reference the conventions section you wrote: error output to stderr, normal output to stdout.

Step 5: What to leave out of GEMINI.md

A GEMINI.md that's too long is worse than no GEMINI.md. It consumes context window space on every session, leaving less room for the actual task. Here's what doesn't belong:

• Source code. Gemini CLI can read your files. Don't duplicate them in GEMINI.md.
• Package lockfiles or dependency trees. pip list is one command away.
• Full README contents. GEMINI.md is a cheat sheet for the agent, not the full project documentation. Link to the README for narrative context.
• Transient state. Don't put "currently working on X" in GEMINI.md. That's what the conversation is for.
• Git history or changelogs. The agent can run git log if it needs to.

A good GEMINI.md is under 80 lines. If yours is longer, you're probably duplicating information the agent can discover on its own.

What goes wrong

Mistake	How you notice it	The fix
GEMINI.md not being loaded	You ask a question about the project and Gemini CLI has no prior knowledge	Check the filename: it must be exactly GEMINI.md (case-sensitive) and in the directory where you run gemini
GEMINI.md too long	Sessions feel cramped, Gemini CLI runs out of context quickly	Trim to under 80 lines. Remove anything the agent can discover by reading files or running commands
/init generates incorrect build commands	pip install fails because the generated GEMINI.md says pip install -e . but you don't have a setup.py	Always review the generated file before committing. /init guesses based on directory contents, not actual project config
Forgetting to update GEMINI.md after a refactor	Gemini CLI suggests old patterns or references directories that don't exist anymore	Treat GEMINI.md like documentation: update it when the project changes. Run gemini -p "Update GEMINI.md to reflect the new directory structure" --yolo after a refactor
Putting secrets in GEMINI.md	API keys or tokens end up in version control	GEMINI.md is committed to git. Never put secrets in it. Use environment variables and reference them in GEMINI.md (process.env.API_KEY, $API_KEY)

Confirm it worked

Open a fresh Gemini CLI session in the weather-cli project and run these prompts without providing any additional context:

cd /tmp/weather-cli
gemini

Send a series of prompts to validate the agent's knowledge. The agent should answer accurately without requiring further explanation.

> How do I run the tests?

> What Python version does this project require?

> What's the main gotcha with the requests library in this project?

> Add a --help flag to main.py that prints usage and exits

If Gemini CLI answers the first three questions correctly (pytest, Python 3.10+, requests needs a timeout) and adds a working --help flag without you explaining where main.py lives or what argument parser to use, your GEMINI.md is doing its job.

Next: Sandbox & Docker Execution