Referencias

Añade directorios locales y repositorios Git como referencias del proyecto.

Las referencias le dan a OpenCode acceso a directorios fuera del proyecto actual. Úsalas para poner a disposición documentación, bibliotecas compartidas, ejemplos u otro repositorio mientras trabajas.

Las referencias se configuran mediante un alias en opencode.json o 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",
    },
  },
}

Directorios Locales

Usa path para referenciar un directorio local.

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

Las rutas pueden ser:

• Relativas al archivo de configuración que define la referencia
• Absolutas, como /home/user/docs
• Relativas a tu directorio personal, como ~/docs

También puedes usar una forma abreviada de cadena:

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

Repositorios Git

Usa repository para referenciar un repositorio Git. OpenCode materializa el repositorio en su caché local de repositorios y pone a disposición el código fuente descargado como directorio de referencia.

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

repository acepta URLs de Git, referencias de tipo host/ruta y la forma abreviada owner/repo de GitHub. El campo opcional branch selecciona una rama o ref. Sin branch, OpenCode usa la rama predeterminada del repositorio.

Puedes usar la forma abreviada de cadena cuando no necesites una rama, descripción u otras opciones:

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

Nota: Las referencias Git se actualizan de forma asíncrona. Un repositorio recién configurado puede tardar un momento en terminar de clonarse o actualizarse.

Describir el Uso

Añade description para explicar cuándo debe usar un agente una referencia.

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

OpenCode incluye en el contexto del agente las referencias que tienen descripción. Las descripciones deben ser breves y lo bastante específicas como para distinguir referencias con contenido similar. Las referencias sin descripción siguen disponibles mediante el autocompletado y el uso directo, pero no se muestran a los agentes.

Ocultar Entradas del Autocompletado

Establece hidden en true para omitir una referencia del autocompletado con @ en la TUI.

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

hidden solo afecta al autocompletado. Una referencia oculta que tenga descripción se sigue incluyendo en el contexto del agente.

Usar Referencias

Las referencias configuradas aparecen en el autocompletado con @ de la TUI. Escribe @alias para adjuntar la raíz de la referencia, o @alias/ para buscar archivos dentro de ella.

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

Los agentes también reciben en su contexto de sistema las rutas resueltas y las descripciones de las referencias configuradas que tienen descripción, de modo que pueden inspeccionar una referencia cuando sea relevante sin que tengas que adjuntarla manualmente.

OpenCode permite automáticamente los directorios de referencia a través de su límite de permiso de directorio externo. Los permisos normales de las herramientas se siguen aplicando; por ejemplo, un agente que no puede editar archivos no obtiene acceso de edición por el hecho de que un directorio esté configurado como referencia.

Campos de Configuración

Los alias de referencia no pueden estar vacíos ni contener /, espacios en blanco, comillas invertidas o comas.