# GEMINI.md tells Gemini your rules. Not your code.

Canonical source: https://maguyva.ai/for-gemini

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

GEMINI.md sets the working context. MCP lets Gemini reach for tools. Maguyva is the MCP server that gives Gemini a queryable map of your repo, so the first edit isn’t a guess at file structure.

> GEMINI.md is the context. MCP is the channel. Maguyva is the map.

## The layered stack

Four ideas. Each one does one job.

### GEMINI.md

How Gemini should behave on this repo.

### MCP

How Gemini reaches for external tools and context.

### Maguyva

The MCP server that returns grounded repo facts.

### Workspaces, not seats

Agents don’t pay seats. [See pricing](https://maguyva.ai/pricing)

## GEMINI.md is a working context. Use it.

Persistent instructions belong in `GEMINI.md`. It is the right place for:

- Build, test, and lint commands Gemini should run.
- “Always do X / never do Y” guardrails scoped to a directory.
- Naming conventions and refactor preferences.
- Pointers to the canonical decision logs and architecture notes.

Keep it concise. Scope it. Commit it.

But `GEMINI.md` was never designed to be a queryable index of every symbol, file, and call site in your repo.

## Where GEMINI.md alone runs out

Four failure modes, one per card.

### // context isn’t an index

Telling Gemini *how to work* doesn’t tell it *what exists*. The first edit on an unfamiliar package is a guess about file paths and function names. GEMINI.md cannot list every symbol, and you wouldn’t want it to.

### // the doc drifts from the code

A GEMINI.md block describing your queue topology is right until someone introduces a new consumer. The code is now the source of truth and the doc is confidently stale. Gemini reads the wrong one.

### // rename is a graph problem

“What references this class?” is not answerable from a markdown file. Gemini either grep-and-prays across the monorepo or asks you to paste call sites into the chat.

### // context windows aren’t free

A large window is not the same as a queryable index. Loading GEMINI.md until Gemini “knows enough” still trades reasoning budget for static context volume.

## How the three layers fit together

Gemini users already think in this shape. The page should make it obvious.

- **GEMINI.md**: context (how Gemini behaves)
- **MCP**: the channel (how it reaches)
- **Maguyva**: codebase facts (what it sees)

- **GEMINI.md**: how Gemini behaves on this repo.
- **MCP**: how Gemini reaches for tools and context. [(spec)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: what Gemini sees when it asks the codebase a question. Semantic, AST, graph, and text search returned with file paths and line numbers.

> GEMINI.md tells Gemini *how to work*.
> Maguyva gives Gemini *something to work from*.

## Three workflows

Gemini-specific. Grounded against the actual call graph, not Gemini’s grep.

### 01. Rename a shared class, find every dependent first

```text
gemini> rename PaymentClient → BillingClient

graph::callers(PaymentClient)            12 references across 7 packages
graph::importers(src/payments/client.ts)  9 importers
graph::extends(PaymentClient)             2 subclasses (RetryClient, MockClient)

→ Gemini proposes a 21-edit migration with the file list inline.
[exit 0]
```

Gemini asks Maguyva for dependents *before* it starts editing. The migration list comes back grounded in the actual graph, not Gemini’s recollection.

### 02. Find the real implementation, not the test stub

```text
gemini> how does normalizePhoneNumber handle E.164?

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← real impl
  test/util/phone.spec.ts:14  jest.mock(...)      ← stub
[exit 0]
```

Names lie. Mocks shadow real code. Maguyva ranks the real implementation above the test mock.

### 03. Check blast radius before a refactor

```text
gemini> what calls QueueDispatcher.publish?

graph::callers(QueueDispatcher.publish)
  3 in src/billing/*    1 in src/audit/*    1 in src/notifications/*
[exit 0]
```

Cross-package call-sites surface inline. The diff is grounded against real importers, not Gemini’s grep.

## Setup in Gemini CLI

Three steps. Free tier: 3 repos, 50K indexed lines, no card.

### 01. Index a repo at maguyva.ai

Pick one you know well, so you can verify the answers.

### 02. Add Maguyva as an MCP server in your Gemini CLI settings

`~/.gemini/settings.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Ask one question whose answer you already know

Don’t start with your whole company. Start with one repo and one verifiable question.

## Index one repo you already know.

Connect Gemini over MCP. Ask one question whose answer you can verify.