For Goose users

Goose runs on extensions. Add one that knows your repo.

Goose does its work through extensions, and every extension is an MCP server. Maguyva is the one that indexes your codebase, so Goose asks where things are instead of listing directories.

Start free Read the Goose setup

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

Use .goosehints for how to work. Use Maguyva for what the code says now.

What Goose needs to know

Four facts specific to Goose.

// config file

config.yaml

Extensions live under extensions in ~/.config/goose/config.yaml. goose configure → Add Extension writes the same kind of entry for you.

// transport

A remote extension

Maguyva is a streamable_http extension, so Goose connects to the endpoint itself: no local process, no Node.js. The URL goes in uri, not url.

// key

headers

Goose sends the headers map with every request, so the key goes in the Authorization header. Goose can also fill it from an environment variable listed under env_keys.

// tool filter

available_tools

An extension can expose a subset of its tools: list the ones you want under available_tools, or leave it empty for all of them.

Goose hints are a working agreement. Use them.

# .goosehints
- Use pnpm, not npm.
- Run the integration tests before you call a change done.

Goose loads AGENTS.md and .goosehints by default: global hints from ~/.config/goose/.goosehints, project hints from the repo, and nested files as it works in subfolders. Hints need the Developer extension. They are the right place for:

Tooling choices and commands.
Conventions Goose should follow.
Where the docs live.

Hints describe the project. They do not answer “what depends on this?”

Where hints and the shell run out

Three gaps Goose fills with shell commands, one file at a time.

// a listing isn’t a map

On an unfamiliar repo, Goose orients with directory listings and file reads. Each one spends context before the task starts.

// grep finds strings, not callers

A text search cannot tell a real call from a comment, a mock, or a method with the same name.

// hints drift

A hints file written last quarter describes last quarter’s layout. Goose follows it anyway.

Maguyva as a Goose extension

One extensions entry gives Goose:

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.
Tools that only read Maguyva’s tools query the index. None of them edit your files.

Hints tell Goose how to work.
Maguyva gives Goose a map of the code.

Two workflows

Map first, then let Goose run.

// workflow 01

Trace a bug to its source

goose> why do some exports finish with zero rows?

semantic_search("export job empty result")
  src/export/runner.ts:118   flushBatch()
  src/export/filters.ts:40   applyTenantFilter()

→ Goose reads two files, not the whole export package.
[exit 0]

Ranked results narrow the search before Goose opens a shell.

// workflow 02

Check dependents before a refactor

goose> split the Notifier class into email and SMS

dependency_search("Notifier", dependents)
  11 references across 5 packages

→ The plan covers all eleven before the first edit.
[exit 0]

Goose gets the full dependent list in one call instead of a chain of greps.

Setup in Goose

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.

// step 02

Add Maguyva to extensions in config.yaml

~/.config/goose/config.yaml

extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

// step 03

Replace the placeholder and start a session

Swap mgv_xxxx for your API key, run goose session, and ask one question whose answer you already know. YAML is indentation-sensitive: use spaces, not tabs.