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

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

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

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.

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

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

### 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`.

### 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`.

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

```text
# .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.

### 01. Trace a bug to its source

```text
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.

### 02. Check dependents before a refactor

```text
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.

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

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

### 02. Add Maguyva to extensions in config.yaml

`~/.config/goose/config.yaml`

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

```

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

Goose’s [extension docs](https://goose-docs.ai/docs/getting-started/using-extensions/) cover remote extensions, timeouts, and tool filters.

## Index one repo you already know.

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