// agreement
copilot-instructions.md
How Copilot should behave on this repo.
For GitHub Copilot CLI users
Copilot starts every session blind.
Custom instructions tell Copilot how to behave. They do not tell Copilot what is in your repo. Maguyva indexes the codebase and serves it back over MCP, so GitHub Copilot CLI edits like it has already read the code.
Free tier: 3 repos, 50K indexed lines, no card.
Use instructions for behavior. Use Maguyva for current codebase facts.The layered stack
Four ideas. Each one does one job.
// transport
MCP
How Copilot 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
Custom instructions are a working agreement. Use them.
# .github/copilot-instructions.md
- Prefer the existing module boundaries.
- Run the repo test command before you propose a merge.
- Do not invent file paths. Ask before you create a new package.Persistent instructions belong in .github/copilot-instructions.md. It is the right place for:
- Build, test, and lint commands Copilot should run.
- “Always do X / never do Y” guardrails scoped to this repo.
- Naming conventions and review preferences.
- Pointers to the decision log — not a dump of every symbol.
That file was never a queryable index of the repo. It tells Copilot how to work. It does not tell Copilot what is there.
Where custom instructions become static at scale
Four failure modes Copilot cannot fix from a markdown file.
// instructions aren’t an index
Telling Copilot how to behave does not tell it which class owns parseConfig, or which package actually implements the public API. The first edit on an unfamiliar tree is a guess at file structure.
// docs go stale, code does not
An instructions block describing last quarter’s auth flow is confidently wrong the day someone splits the session store. Copilot will prefer the file you committed over the code that shipped.
// dependencies aren’t in markdown
“What imports this?” is a graph question. Instructions cannot list every caller, and you would not want them to.
// context windows have a budget
Stuffing more of the repo into instructions trades reasoning tokens for a stale snapshot. Past a few KB you are paying for a worse map.
Maguyva as the added layer
Copilot already thinks in instructions and tools.
copilot-instructions.md
agreement
how Copilot behaves
MCP
the channel
how it reaches
Maguyva
codebase facts
what it sees
- A queryable map of the repo served over MCP as a remote streamable-HTTP server.
- 11 customer-facing tools across semantic, structural (AST), graph, and text search, plus symbols, dependents, and file retrieval.
- Ranked results with file paths and line numbers across 284+ languages and text-based technologies.
- One config The same workspace answers in Copilot, Claude Code, Cursor, Codex, and any other MCP-compatible client.
Custom instructions tell Copilot how to behave.
Maguyva gives Copilot a queryable map of the code.
Three workflows
Ask the map before you accept the diff.
// workflow 01
Find the real implementation, not the test stub
copilot> 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 → Copilot opens the implementation, not the mock. [exit 0]
Names lie. Mocks shadow real code. Maguyva ranks the real implementation above the test mock.
// workflow 02
Check blast radius before you refactor
copilot> what calls QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 in src/billing/* 1 in src/audit/* 1 in src/notifications/* → The diff is grounded against real importers. [exit 0]
Cross-package call-sites surface inline. The diff is grounded against real importers, not Copilot’s grep.
// workflow 03
Rename a shared class, find every dependent first
copilot> 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) → Copilot proposes a migration with the file list inline. [exit 0]
Copilot asks Maguyva for dependents before it starts editing. The migration list comes back grounded in the actual graph, not Copilot’s recollection.
Setup in GitHub Copilot CLI
Three steps. Free tier: 3 repos, 50K indexed lines, no card.
// step 01
Index a repo at maguyva.ai
Pick one you already know, so you can grade the answers. Sign up free, connect GitHub, wait for the index.
// step 02
Add Maguyva as a remote MCP server in Copilot
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp~/.copilot/mcp-config.json{ "mcpServers": { "maguyva": { "type": "http", "url": "https://maguyva.tools/mcp", "headers": { "Authorization": "Bearer mgv_xxxx" } } } }// step 03
Ask one question whose answer you already know
Do not start with the whole company. Ask one question whose answer you already know, then open the cited file.