Skip to content

For Gemini CLI users

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

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.

Index your first repo Read the Gemini setup

Public beta. Free tier: 3 repos, 50K indexed lines, no card.

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

The layered stack

Four ideas. Each one does one job.

// context

GEMINI.md

How Gemini should behave on this repo.

// transport

MCP

How Gemini reaches for external tools and context.

// codebase

Maguyva

The MCP server that returns grounded repo facts.

// who pays

Workspaces, not seats

Agents don’t pay seats. See 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)
  • 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.

// workflow 01

Rename a shared class, find every dependent first

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.

// workflow 02

Find the real implementation, not the test stub

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.

// workflow 03

Check blast radius before a refactor

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.

  1. // step 01

    Index a repo at maguyva.ai

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

  2. // step 02

    Add Maguyva as an MCP server in your Gemini CLI settings

    // ~/.gemini/settings.json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

  3. // step 03

    Ask one question whose answer you already know

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

Public beta. Self-serve signups open.

Index one repo you already know.

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

Get a beta spot See compatibility docs

free plan: 3 repos, 50K indexed lines, no card.