How to write a GEMINI.md for Gemini CLI and Antigravity

GEMINI.md is the brain file for Google's coding agents. Put one in your project and the agent loads it automatically, so you stop re-explaining your stack, your commands, and your "please never do that" rules in every new chat.

It's read by two tools that work a little differently: Gemini CLI and Google Antigravity (the app, the IDE, and the Antigravity CLI). The basics are the same, but imports and scoped rules aren't, and that's where most setups quietly break. This guide covers both.

Where each tool looks

Both tools combine every file they find instead of picking one. Global rules, project rules, and folder rules all end up in the prompt together. Antigravity's docs say the more specific folder rule wins a conflict. Gemini CLI simply joins the files together in order. Either way, the safe habit is the same: don't write rules that contradict each other across levels.

Note the shared home folder: both tools read ~/.gemini/GEMINI.md. If you use both, your global preferences apply in both.

1. Create GEMINI.md in the project root

GEMINI.md is plain Markdown with no frontmatter. Antigravity treats the whole file as always on for its folder. Here's a solid starting point for a small web app:

# GEMINI.md: Pixel Pantry

## Project
Mobile-first web app that tracks what's in my fridge and suggests recipes.
Audience: me and my roommates. v1 = add items, expiry dates, recipe ideas.

## Stack (do not change without asking)
- Vite 6, vanilla JavaScript (ES modules), plain CSS
- Data in localStorage; no backend yet
- Node 22

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Build: `npm run build` (outputs dist/)
- Tests: `npm test`

## Code map
- src/pages/: one file per screen
- src/lib/: storage and helpers, no DOM code
- public/: static files copied as-is

## Always
- Make the smallest change that solves the task
- Run `npm test` and `npm run build` before saying you're done
- Explain what changed in plain language

## Never
- Add an npm package without asking
- Put API keys or tokens in code; secrets live in .env (gitignored)
- Rewrite files I didn't mention

## Done means
Build passes, tests pass, no console errors, works at 375px wide.

That's about 35 lines, and it already prevents the classic mistakes: surprise frameworks, guessed commands, and keys in front-end code. If you'd rather not type it, the Brain File Generator writes a GEMINI.md from a short form. For the reasoning behind each section, see what a brain file is.

2. Put personal preferences in the global file

Things that are true about you rather than the project go in ~/.gemini/GEMINI.md (on Windows, that's C:\Users\<you>\.gemini\GEMINI.md):

# About me
- I'm on Windows 11 and use PowerShell; give PowerShell commands, not bash
- I'm learning: explain changes briefly and simply
- Ask before deleting files or running anything that costs money

Keep project facts out of the global file. They belong in the repo, where they get committed along with the code and work on any machine.

In Gemini CLI, telling the agent "remember that I prefer pnpm" makes it save that fact to one of these Markdown memory files. Read what it wrote now and then and tidy it up. A memory file nobody prunes slowly fills up with stale rules.

3. Add folder-level files where conventions differ

A monorepo or a project with a game client and a server often needs different rules in different places. Drop a small GEMINI.md into that folder:

server/GEMINI.md

# Server rules
- Python 3.12 + FastAPI; run tests with `pytest -q` from server/
- Every new endpoint needs a test in server/tests/
- Never log request bodies (they can contain user data)

Both tools pick it up when the agent works on files in server/, so the rest of the project doesn't pay for those lines on every request. This is the easiest way to keep the root file short.

4. Split long rules: imports vs. scoped rules

This is where the two tools really differ.

Gemini CLI: @file imports

Gemini CLI can pull other Markdown files into GEMINI.md with an @ on its own line. Relative and absolute paths both work:

# GEMINI.md
Core rules are below.

@./docs/brain/architecture.md
@./docs/brain/style-guide.md

Antigravity: @[label](path) and .agents/rules/

Antigravity uses a different include syntax. @[label](path) pastes the file's contents in, while a bare @path only turns into a file reference the agent can open:

Follow our API standards:
@[API standards](docs/api-standards.md)

Before changing database models, check @src/db/schema.ts.

Antigravity also supports scoped rule files in .agents/rules/. The older .agent/rules/ folder still works. Unlike GEMINI.md, each of these files must start with YAML frontmatter that sets a trigger:

.agents/rules/database.md

---
trigger: model_decision
description: "Use when writing or reviewing database migrations or schema changes."
---

# Database rules
1. Never drop or rename a column in one release; add the new one first.
2. Every migration must be reversible.

• always_on: loaded on every turn. For these you can usually just use GEMINI.md instead.
• model_decision: only the description is shown up front, and the agent reads the full rule when the task matches. description is required. This is best for detailed topic guides.
• glob: activates when the agent works on matching files, for example globs: "*.gd, *.tscn". Quote patterns that start with *.
• manual: only used when you @-mention the rule in chat. Good for release checklists.

This is the same layering idea as the knowledge folder and scoped rules in the long-term memory guide, adapted to Google's tools.

5. Check what actually loaded

Don't just assume your rules are active. Check:

• Gemini CLI: the footer shows how many context files loaded. /memory show prints the exact combined text the model gets, and /memory reload rescans after you edit a file.
• Antigravity: open the agent panel's … menu, then Customizations, then the Rules tab, to see global and workspace rules (and create new ones).
• Quick test for either: start a new session and ask "What are the rules for this project, and what command runs the tests?" If the answer doesn't match your file, it isn't loaded.

Keep it short (there are real limits)

Every line of an always-on file is sent on every turn. Antigravity enforces this: it truncates any single rule file over 24,000 bytes, and all global and always-on rules share a budget of about 20,000 tokens. Past that, it swaps the largest files for pointers the agent has to open on its own. Its IDE docs also mention a 12,000-character limit per rules file. A good target is under 150 lines in the root GEMINI.md, with the details moved to folder files, scoped rules, or linked docs.

Using other AI tools too? Share AGENTS.md

If the same repo is also used with Codex, Cursor, or Claude Code, keep one source of truth:

• Antigravity reads AGENTS.md natively, alongside GEMINI.md.
• Gemini CLI can be pointed at it with the context.fileName setting in settings.json:

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

Then put your real rules in AGENTS.md and either delete GEMINI.md or reduce it to Gemini-only notes. Don't keep the same rules in both. The tools load both files, so you'd pay for every rule twice, and the copies drift apart over time. The rules file formats guide covers the other tools' file names.

Checklist

• GEMINI.md (or AGENTS.md) in the project root, no frontmatter, under ~150 lines
• Personal preferences in ~/.gemini/GEMINI.md, project facts in the repo
• Folder files only where the conventions really differ
• Every .agents/rules/*.md file has valid frontmatter with a trigger
• No secrets in any rules file, ever: they're committed and sent to the model
• Checked with /memory show or the Rules panel, and tested with a fresh session
• Committed to git so your AI's brain is versioned and backed up