# O Goose roda com extensões. Adicione uma que conheça o seu repositório.

Canonical source: https://maguyva.ai/pt-br/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).

O Goose trabalha por meio de extensões, e cada extensão é um servidor MCP. O Maguyva é a que indexa a sua base de código, então o Goose pergunta onde as coisas estão em vez de listar diretórios.

> Use .goosehints para como trabalhar. Use o Maguyva para o que o código diz agora.

## O que você precisa saber sobre o Goose

Quatro fatos específicos do Goose.

### config.yaml

As extensões ficam em `extensions` no `~/.config/goose/config.yaml`. `goose configure` → Add Extension escreve o mesmo tipo de entrada por você.

### Uma extensão remota

O Maguyva é uma extensão `streamable_http`, então o Goose se conecta ao endpoint por conta própria: sem processo local, sem Node.js. A URL vai em `uri`, não em `url`.

### headers

O Goose envia o mapa `headers` em toda requisição, então a chave vai no cabeçalho `Authorization`. O Goose também pode preenchê-la a partir de uma variável de ambiente listada em `env_keys`.

### available_tools

Uma extensão pode expor só parte das ferramentas: liste as que você quer em `available_tools`, ou deixe vazio para todas.

## As hints do Goose são um acordo de trabalho. Use-as.

```text
# .goosehints
- Use pnpm, não npm.
- Rode os testes de integração antes de dar uma mudança por concluída.
```

O Goose carrega por padrão o `AGENTS.md` e o `.goosehints`: hints globais de `~/.config/goose/.goosehints`, hints do projeto a partir do repositório e arquivos aninhados quando trabalha em subpastas. As hints exigem a extensão Developer. São o lugar certo para:

- Escolhas de ferramentas e comandos.
- Convenções que o Goose deve seguir.
- Onde fica a documentação.

As hints descrevem o projeto. Elas não respondem “o que depende disto?”

## Onde as hints e o shell não dão conta

Três lacunas que o Goose preenche com comandos de shell, um arquivo por vez.

### // uma listagem não é um mapa

Num repositório desconhecido, o Goose se orienta com listagens de diretórios e leituras de arquivos. Cada uma gasta contexto antes de a tarefa começar.

### // grep acha strings, não chamadores

Uma busca de texto não distingue uma chamada real de um comentário, de um mock ou de um método com o mesmo nome.

### // hints ficam defasadas

Um arquivo de hints escrito no trimestre passado descreve a estrutura do trimestre passado. O Goose segue mesmo assim.

## O Maguyva como extensão do Goose

Uma entrada em extensions dá ao Goose:

- **11 ferramentas sobre o seu repositório indexado**: busca semântica, estrutural (AST), de grafo e de texto, além de busca de símbolos, dependentes e recuperação de arquivos.
- **Respostas com caminhos de arquivo e números de linha**: em mais de 285 linguagens.
- **Ferramentas que só leem**: As ferramentas do Maguyva consultam o índice. Nenhuma edita os seus arquivos.

> As hints dizem ao Goose *como trabalhar*.
> O Maguyva dá ao Goose *um mapa do código*.

## Dois fluxos de trabalho

Primeiro o mapa, depois deixe o Goose rodar.

### 01. Rastrear um bug até a origem

```text
goose> por que algumas exportações terminam com zero linhas?

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

→ O Goose lê dois arquivos, não o pacote export inteiro.
[exit 0]
```

Resultados priorizados afunilam a busca antes de o Goose abrir um shell.

### 02. Verificar dependentes antes de uma refatoração

```text
goose> divida a classe Notifier em e-mail e SMS

dependency_search("Notifier", dependents)
  11 referências em 5 pacotes

→ O plano cobre as onze antes da primeira edição.
[exit 0]
```

O Goose recebe a lista completa de dependentes numa só chamada, em vez de uma sequência de greps.

## Configuração no Goose

Três passos. Plano Free: 3 repositórios, Até 50 mil linhas de repositório indexadas, sem cartão.

### 01. Indexe um repositório em maguyva.ai

Escolha um que você já conheça, para poder avaliar as respostas.

### 02. Adicione o Maguyva a extensions no 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. Troque o placeholder e inicie uma sessão

Troque `mgv_xxxx` pela sua chave de API, rode `goose session` e faça uma pergunta cuja resposta você já saiba. YAML é sensível à indentação: use espaços, não tabs.

A [documentação de extensões](https://goose-docs.ai/docs/getting-started/using-extensions/) do Goose cobre extensões remotas, timeouts e filtros de ferramentas.

## Indexe um repositório que você já conhece.

Conecte o Goose via MCP e faça uma pergunta que você consiga conferir.