Referências

Adicione diretórios locais e repositórios Git como referências de projeto.

As referências dão ao OpenCode acesso a diretórios fora do projeto atual. Use-as para disponibilizar documentação, bibliotecas compartilhadas, exemplos ou outro repositório enquanto você trabalha.

As referências são configuradas por alias no opencode.json ou opencode.jsonc.

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}

Diretórios Locais

Use path para referenciar um diretório local.

{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}

Os caminhos podem ser:

• Relativos ao arquivo de config que define a referência
• Absolutos, como /home/user/docs
• Relativos ao seu diretório home, como ~/docs

Você também pode usar uma forma abreviada com string:

{
  "references": {
    "docs": "../docs",
  },
}

Repositórios Git

Use repository para referenciar um repositório Git. O OpenCode materializa o repositório no seu cache local de repositórios e disponibiliza o código já obtido (checked-out) como um diretório de referência.

{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

repository aceita URLs Git, referências no formato host/path e a forma abreviada owner/repo do GitHub. O campo opcional branch seleciona uma branch ou ref. Sem branch, o OpenCode usa a branch padrão do repositório.

Você pode usar a forma abreviada com string quando não precisar de branch, descrição ou outras opções:

{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

Nota: As referências Git são atualizadas de forma assíncrona. Um repositório recém-configurado pode levar um momento para terminar de clonar ou atualizar.

Descreva o Uso

Adicione description para explicar quando um agente deve usar uma referência.

{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}

O OpenCode inclui no contexto do agente as referências que têm descrição. As descrições devem ser curtas e específicas o suficiente para distinguir referências com conteúdo semelhante. Referências sem descrição continuam disponíveis via autocomplete e uso direto, mas não são anunciadas aos agentes.

Ocultar Entradas do Autocomplete

Defina hidden como true para omitir uma referência do autocomplete com @ na TUI.

{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}

hidden afeta apenas o autocomplete. Uma referência oculta que tenha descrição continua incluída no contexto do agente.

Usando Referências

As referências configuradas aparecem no autocomplete com @ da TUI. Digite @alias para anexar a raiz da referência, ou @alias/ para pesquisar arquivos dentro dela.

Compare this implementation with @sdk/src/client.ts

Os agentes também recebem os caminhos resolvidos e as descrições das referências configuradas que têm descrição no contexto de sistema deles, para que possam inspecionar uma referência quando for relevante sem que você precise anexá-la manualmente.

O OpenCode permite automaticamente diretórios de referência através do limite de permissão de diretório externo. As permissões normais de ferramentas continuam se aplicando; por exemplo, um agente que não pode editar arquivos não ganha acesso de edição só porque um diretório está configurado como referência.

Campos de Configuração

Os aliases de referência não podem ficar vazios nem conter /, espaços em branco, crases ou vírgulas.