Skip to content

For Codex CLI users

AGENTS.md tells Codex how to work.
Not what's there.

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

Index your first repo Read the Codex setup

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

AGENTS.md is the agreement. MCP is the channel. Maguyva is the map.

The layered stack

Four ideas. Each one does one job.

// agreement

AGENTS.md

How Codex should behave on this repo.

// transport

MCP

How Codex 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

AGENTS.md is a working agreement. Use it.

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

  • Build, test, and lint commands Codex 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 AGENTS.md was never designed to be a queryable index of every symbol, file, and call site in your repo.

Where AGENTS.md alone becomes static at scale

Four failure modes, one per card.

// agreements aren’t an index

Telling Codex 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. AGENTS.md cannot list every symbol, and you wouldn’t want it to.

// the doc drifts from the code

An AGENTS.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. Codex reads the wrong one.

// rename is a graph problem

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

// context windows aren’t free

Stuffing AGENTS.md until Codex “knows enough” eats tokens that should pay for reasoning. Past a few KB you trade answer quality for static context volume.

How the three layers fit together

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

AGENTS.md

agreements

how Codex behaves

MCP

the channel

how it reaches

Maguyva

codebase facts

what it sees

  • AGENTS.md how Codex behaves on this repo.
  • MCP how Codex reaches for tools and context. (spec)
  • Maguyva what Codex sees when it asks the codebase a question. Semantic, AST, graph, and text search returned with file paths and line numbers.

AGENTS.md tells Codex how to work.

Maguyva gives Codex something to work from.

Three workflows

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

// workflow 01

Rename a shared class, find every dependent first

codex> 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)

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

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

// workflow 02

Find the real implementation, not the test stub

codex> 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

codex> 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 Codex’s grep.

Setup in Codex 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 Codex config

    $ export MAGUYVA_API_KEY=mgv_xxxx
$ codex mcp add maguyva --url https://maguyva.tools/mcp \
    --bearer-token-env-var MAGUYVA_API_KEY

# equivalent ~/.codex/config.toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_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 Codex 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.