# Gemini CLI and Antigravity setup with AGENTS.md > Point Gemini CLI at AGENTS.md with context.fileName, and set up Antigravity's .agents/ rules, skills, hooks and MCP. Real files from a generated Next.js repo. *Updated 2026-10-08.* Google has two coding agents, and they set up differently. Gemini CLI reads GEMINI.md unless you point it at AGENTS.md. Antigravity reads AGENTS.md and the shared `.agents/` folder as they are. Which one you use depends on your account. On 2026-06-18, consumer accounts (free, Pro and Ultra) moved from Gemini CLI to Antigravity CLI. Gemini CLI still works with paid API keys and Code Assist. Below: both setups, with the real files from a generated Next.js repo. ## The two side by side | | Gemini CLI | Antigravity | |---|---|---| | Instructions | GEMINI.md. AGENTS.md through `context.fileName` | AGENTS.md and GEMINI.md, root and nested | | Rules | Inside the instruction files | `.agents/rules/*.md`, each with a `trigger` | | Skills | `.agents/skills/` | `.agents/skills/`, run as `/name` | | Subagents | `.gemini/agents/*.md` | `.agents/agents/*.md` | | Hooks | `hooks` in `.gemini/settings.json` | `.agents/hooks.json` | | MCP | `mcpServers` in `.gemini/settings.json` | `.agents/mcp_config.json` | ## Gemini CLI ### GEMINI.md vs AGENTS.md Gemini CLI loads GEMINI.md by default. The `context.fileName` setting changes which file names it loads, and it takes a list. So you don't need a GEMINI.md at all: list AGENTS.md and Gemini CLI reads the same file every other agent reads. The generated `.gemini/settings.json` does exactly that, and holds the hooks and MCP servers too: ```json { "$schema": "https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json", "context": { "fileName": [ "AGENTS.md", "GEMINI.md" ] }, "hooks": { "AfterTool": [ { "matcher": "replace|write_file", "hooks": [ { "name": "auto-lint", "type": "command", "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs auto-lint --from gemini", "timeout": 60000 }, { "name": "enforce-doc-meta", "type": "command", "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs enforce-doc-meta --from gemini", "timeout": 60000 }, { "name": "env-leak-detector-write", "type": "command", "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs env-leak-detector-write --from gemini", "timeout": 60000 } ] } ], "BeforeTool": [ { "matcher": "grep_search|read_file|read_many_files|run_shell_command", "hooks": [ { "name": "env-leak-detector", "type": "command", "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs env-leak-detector --from gemini", "timeout": 60000 } ] }, { "matcher": "run_shell_command", "hooks": [ { "name": "block-destructive", "type": "command", "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs block-destructive --from gemini", "timeout": 60000 }, { "name": "enforce-typecheck", "type": "command", "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs enforce-typecheck --from gemini", "timeout": 60000 }, { "name": "guard-neon-sql", "type": "command", "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs guard-neon-sql --from gemini", "timeout": 60000 } ] } ] }, "mcpServers": { "better-auth": { "httpUrl": "https://mcp.better-auth.com/mcp" }, "neon": { "httpUrl": "https://mcp.neon.tech/mcp?readonly=true" }, "posthog": { "httpUrl": "https://mcp.posthog.com/mcp?readonly=true" }, "sentry": { "httpUrl": "https://mcp.sentry.dev/mcp" }, "stripe": { "httpUrl": "https://mcp.stripe.com" } } } ``` *`.gemini/settings.json`, as generated.* `fileName` lists AGENTS.md first, then GEMINI.md. No GEMINI.md ships. Add one later for Gemini-only notes, and it loads next to AGENTS.md. ### Hooks The `hooks` block in that file holds the guards. `BeforeTool` fires before a tool runs and can block it. `AfterTool` fires after it. Matchers use Gemini's tool names: `run_shell_command`, `read_file`, `write_file`, `replace`. - **One launcher.** Each hook runs `.agents/hooks/run.mjs --from gemini`, from `$GEMINI_PROJECT_DIR`, the project root. It turns Gemini's payload into the format the guards speak. - **Exit 2 blocks,** and the reason goes back to the agent. - **`timeout` is in milliseconds here.** 60000 is one minute. - **Trust first.** Gemini CLI runs a project's hooks, MCP servers and subagents only in a folder you trust. Two limits outside Claude Code: a rewrite becomes a block that names the command to run instead, and hiding a secret in command output doesn't happen. More: [guard hooks in every agent](/guides/ai-coding-agent-hooks). ### Subagents Gemini CLI reads subagents from `.gemini/agents/`, one markdown file each, with a name, a description and a tool list in the frontmatter. The top of the generated PR reviewer: ````markdown --- description: Reviews a diff against this repo's rules before it becomes a PR. Convention-aware, blocking on correctness and security, advisory on taste. name: pr-reviewer tools: - read_file - read_many_files - grep_search - glob - list_directory - run_shell_command --- ```` *First 11 of 92 lines of `.gemini/agents/pr-reviewer.md`.* No `write_file` and no `replace`, so the reviewer reads and runs checks but can't edit. Send a task straight to one with `@pr-reviewer` at the start of your prompt. ### MCP and skills The `mcpServers` block lists remote servers with `httpUrl`. Sign in to one with `/mcp auth `. Neon and PostHog connect read-only. Gemini CLI reads skills from `.agents/skills/`. We checked on Gemini CLI 0.63. Ask for one by name, like "run the setup skill". The Compound Engineering plugin has no Gemini CLI install path yet. The repo's own 29 skills work either way. ## Antigravity ### AGENTS.md and .agents/rules Antigravity reads AGENTS.md and GEMINI.md at the root and in subfolders. They need no frontmatter, and each stays active for its folder. It also reads rule files from `.agents/rules/`. Each one must start with a `trigger`: `always_on`, `glob`, `model_decision` or `manual`. A file without a valid trigger is dropped. Antigravity caps a rule file at 24 KB, and always-on rules share a 20,000-token budget. A generated repo puts every rule in `.agents/rules/` in full, and sets each trigger so nothing loads twice: - **A rule the AGENTS.md files carry in full** gets `trigger: manual`. Antigravity already has it from them. - **A rule some AGENTS.md only links to** (its folder ran out of room) gets `trigger: glob`, for exactly the folders where it was linked. The Stripe webhook rule is the second kind: ```markdown --- description: Verify every Stripe webhook, keep every handler idempotent globs: src/lib/billing/provider.ts, src/lib/billing/webhook.ts trigger: glob --- # Verify every Stripe webhook, keep every handler idempotent Applies to: `src/app/api/webhooks/stripe/**`, `src/lib/billing/provider.ts`, `src/lib/billing/webhook.ts` ``` *First 9 of 72 lines of `.agents/rules/stripe-webhook-integrity.md`.* ### Skills and subagents Antigravity reads Agent Skills from `.agents/skills/` and runs them as `/name`. Start with `/setup` on a fresh clone. Subagent prompts come from `.agents/agents/`: a name, a description and the prompt. Both folders ship in every generated repo, so Antigravity needs no copies. ### Hooks: .agents/hooks.json Antigravity reads workspace hooks from `.agents/hooks.json`. Each hook has a name, and each name maps to its events. Matchers use Antigravity's tool names: `run_command`, `view_file`, `write_to_file`, `replace_file_content`. The first two guards in the generated file: ```json { "auto-lint": { "PostToolUse": [ { "matcher": "multi_replace_file_content|replace_file_content|write_to_file", "hooks": [ { "type": "command", "command": "bun .agents/hooks/run.mjs auto-lint --from antigravity", "timeout": 60 } ] } ] }, "block-destructive": { "PreToolUse": [ { "matcher": "run_command", "hooks": [ { "type": "command", "command": "bun .agents/hooks/run.mjs block-destructive --from antigravity", "timeout": 60 } ] } ] }, ``` *First 29 of 100 lines of `.agents/hooks.json`.* The launcher reads Antigravity's payload, where the call arrives as `toolCall`, and answers with `decision: "deny"` and a reason when a guard blocks. The same two limits apply as in Gemini CLI. ### MCP: .agents/mcp_config.json ```json { "mcpServers": { "better-auth": { "serverUrl": "https://mcp.better-auth.com/mcp" }, "neon": { "serverUrl": "https://mcp.neon.tech/mcp?readonly=true" }, "posthog": { "serverUrl": "https://mcp.posthog.com/mcp?readonly=true" }, "sentry": { "serverUrl": "https://mcp.sentry.dev/mcp" }, "stripe": { "serverUrl": "https://mcp.stripe.com" } } } ``` *`.agents/mcp_config.json`, as generated.* Remote servers use `serverUrl`. Approve each tool the first time it runs. Local servers that need a key, like Postmark or Supabase, are left out of this file: it has no safe way to read a variable. `SETUP.md` says so. Install the Compound Engineering plugin with `agy plugin install https://github.com/EveryInc/compound-engineering-plugin`. ## Setup checklists Gemini CLI: 1. Open the repo and trust the folder. 2. Ask for the setup skill. It fills `.env.local` and connects the services, after you say yes. 3. Sign in to each MCP server with `/mcp auth `. 4. Run `bun run verify:hooks` to see every guard block in Gemini's format. Antigravity: 1. Open the repo and run `/setup`. 2. Approve each MCP tool the first time it runs. 3. Install the plugin with the `agy` command above. 4. Run `bun run verify:hooks` to see every guard block in Antigravity's format. ## Get a repo that works in both Pick your stack at [/build](/build). Gemini CLI and Antigravity are two of 10 agents, all on by default. You get AGENTS.md and its nested files, `.agents/` with every rule, skill, subagent and guard, `.gemini/` for Gemini CLI, and Antigravity's hook and MCP files. The same repo works in Claude Code, Codex, Cursor, Copilot and the rest. $99 once, with lifetime updates. What each agent gets: [the agentic layer](/docs/the-agentic-layer). More: [AGENTS.md examples](/guides/agents-md-examples), [Agent Skills in every agent](/guides/agent-skills-every-agent), [CLAUDE.md vs AGENTS.md](/guides/claude-md-vs-agents-md). ## FAQ ### Does Gemini CLI read AGENTS.md? Not by default. It reads GEMINI.md. Set `context.fileName` in `.gemini/settings.json` to a list that includes AGENTS.md, like `["AGENTS.md", "GEMINI.md"]`, and it loads both. ### Should I use GEMINI.md or AGENTS.md? AGENTS.md, if any other agent works in the repo. Gemini CLI reads it once `context.fileName` lists it, and Antigravity reads both names. Keep GEMINI.md for Gemini-only notes. ### Where do Antigravity rules go? In AGENTS.md files, root and nested, with no frontmatter. Or in `.agents/rules/`, one `.md` file each, starting with a `trigger`: `always_on`, `glob`, `model_decision` or `manual`. ### Where do Antigravity skills go? In `.agents/skills//SKILL.md`, the Agent Skills folder most other agents read too. Run one as `/name`. ### Does Gemini CLI support hooks? Yes. Hooks live under `hooks` in `.gemini/settings.json`. A `BeforeTool` hook that exits 2 blocks the tool call. Project hooks run only in a trusted folder. ### Can I still use Gemini CLI? Yes, with a paid API key or Code Assist. Free, Pro and Ultra consumer accounts moved to Antigravity CLI on 2026-06-18. ## Sources - [Gemini CLI docs: GEMINI.md files](https://geminicli.com/docs/cli/gemini-md) - [Gemini CLI docs: Hooks](https://geminicli.com/docs/hooks/) - [Gemini CLI docs: Subagents](https://geminicli.com/docs/core/subagents/) - [Antigravity docs: Rules](https://antigravity.google/docs/rules) - [Antigravity docs: Agent Skills](https://antigravity.google/docs/skills) - [Antigravity docs: Hooks](https://antigravity.google/docs/hooks) - [Antigravity docs: MCP](https://antigravity.google/docs/mcp) ## Generate it [Build your repo](https://agenticboilerplate.com/build) --- Agentic Boilerplate: A Next.js repo your agent already knows. $99 once. Lifetime access and updates. - Site map for agents: https://agenticboilerplate.com/llms.txt - Public API: https://agenticboilerplate.com/openapi.json - Contact: agenticstudio@gmail.com