# AGENTS.md tells OpenCode your rules. Maguyva shows it the code.

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

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

OpenCode reads AGENTS.md for how to work and calls MCP servers for everything else. Maguyva is a remote MCP server that gives OpenCode a queryable map of your repo, with file paths and line numbers.

> One remote entry under mcp. Nothing runs locally.

## What OpenCode needs to know

Four facts specific to OpenCode.

### opencode.json

Add the server under `mcp` in your project’s `opencode.json`, or in `~/.config/opencode/opencode.json` for every project.

### type: remote

OpenCode connects to Maguyva’s endpoint over HTTP. Nothing runs locally and Node.js is not needed.

### An env reference

OpenCode substitutes environment variables in its config, so the header reads `Bearer {env:MAGUYVA_API_KEY}` and the key stays out of the file you commit.

### Scope it per agent

Every MCP server adds tool definitions to the context. OpenCode can switch a server’s tools off globally with a glob like `"maguyva*": false` and back on for the agents that need them.

## AGENTS.md is a working agreement. Use it.

```text
> /init
# scans the repo and writes AGENTS.md
```

OpenCode reads `AGENTS.md` in the project root and `~/.config/opencode/AGENTS.md` for personal rules. Without an `AGENTS.md`, it falls back to `CLAUDE.md`. Keep it for:

- Build, test, and lint commands.
- Conventions and boundaries the agent should respect.
- Pointers to the docs that matter.

A scan at `/init` time is a summary, not an index. It will not tell OpenCode who calls a function added yesterday.

## Where AGENTS.md runs out

Three gaps OpenCode fills with grep and patience.

### // a summary isn’t an index

AGENTS.md can name the important packages. It cannot list every symbol and call site, and it should not try.

### // grep finds strings, not callers

A text match cannot tell a real call from a comment, a mock, or a method with the same name on another class.

### // the file drifts

AGENTS.md is right the day it is written. The code keeps moving; the file changes when someone remembers to update it.

## Maguyva as a remote MCP server in OpenCode

One entry under mcp gives OpenCode:

- **11 tools over your indexed repo**: semantic, structural (AST), graph, and text search, plus symbol lookup, dependents, and file retrieval.
- **Answers with file paths and line numbers**: across 285+ languages.
- **The same answers for every model**: OpenCode works with many model providers. Maguyva returns the same map whichever model asks.

> AGENTS.md tells OpenCode *how to work*.
> Maguyva gives OpenCode *something to work from*.

## Two workflows

Ask the map from the same terminal.

### 01. Rename a shared type across packages

```text
opencode> rename OrderStatus to FulfillmentStatus

dependency_search("OrderStatus", dependents)
  23 references across 8 packages
structural_search(switch_statement, "OrderStatus")
  4 exhaustive switches

→ OpenCode edits the full list, switches included.
[exit 0]
```

The exhaustive switches are the ones a text search misses and the compiler catches late.

### 02. Tell code from documentation

```text
opencode> where is FEATURE_BULK_EXPORT read?

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← docs only

→ Two code paths, one stale doc.
[exit 0]
```

Exact matches come back with paths, so OpenCode can tell code from documentation before it edits either.

## Setup in OpenCode

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

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

Pick one you already know, so you can grade the answers.

### 02. Add Maguyva under mcp in opencode.json

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Export your key and check the connection

Set `MAGUYVA_API_KEY` in the shell that starts OpenCode. `opencode mcp list` shows each configured server; then ask one question whose answer you already know.

OpenCode’s [MCP docs](https://opencode.ai/docs/mcp-servers/) cover timeouts, OAuth, and per-agent tool access.

## Index one repo you already know.

Connect OpenCode over MCP, then ask one question you can check.