# Referenzen

> Dies ist die Doku für OpenCode V1. Die aktuelle Doku für OpenCode V2 findest du unter https://opencode.ai/docs/llms.txt.

Referenzen geben OpenCode Zugriff auf Verzeichnisse außerhalb des aktuellen Projekts. Verwenden Sie sie, um Dokumentation, gemeinsam genutzte Bibliotheken, Beispiele oder ein anderes Repository während der Arbeit verfügbar zu machen.

Referenzen werden über einen Alias in `opencode.json` oder `opencode.jsonc` konfiguriert.

```jsonc title="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",
    },
  },
}
```

---

## Lokale Verzeichnisse

Verwenden Sie `path`, um auf ein lokales Verzeichnis zu verweisen.

```jsonc title="opencode.jsonc"
{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}
```

Pfade können sein:

- Relativ zur Konfigurationsdatei, die die Referenz definiert
- Absolut, z. B. `/home/user/docs`
- Relativ zu Ihrem Home-Verzeichnis, z. B. `~/docs`

Sie können auch eine Kurzschreibweise als String verwenden:

```jsonc title="opencode.jsonc"
{
  "references": {
    "docs": "../docs",
  },
}
```

---

## Git-Repositories

Verwenden Sie `repository`, um auf ein Git-Repository zu verweisen. OpenCode legt das Repository in seinem lokalen Repository-Cache an und stellt den ausgecheckten Quellcode als Referenzverzeichnis bereit.

```jsonc title="opencode.jsonc"
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}
```

`repository` akzeptiert Git-URLs, host/path-Referenzen und die GitHub-Kurzform `owner/repo`. Das optionale Feld `branch` wählt einen Branch oder Ref aus. Ohne `branch` verwendet OpenCode den Standard-Branch des Repositorys.

Sie können die Kurzschreibweise als String verwenden, wenn Sie keinen Branch, keine Beschreibung und keine weiteren Optionen benötigen:

```jsonc title="opencode.jsonc"
{
  "references": {
    "effect": "Effect-TS/effect",
  },
}
```

:::note
Git-Referenzen werden asynchron aktualisiert. Bei einem neu konfigurierten Repository kann es einen Moment dauern, bis das Klonen oder Aktualisieren abgeschlossen ist.
:::

---

## Verwendung beschreiben

Fügen Sie `description` hinzu, um zu erklären, wann ein Agent eine Referenz verwenden soll.

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

OpenCode nimmt Referenzen mit Beschreibungen in den Agentenkontext auf. Beschreibungen sollten kurz und so spezifisch sein, dass sich Referenzen mit ähnlichem Inhalt unterscheiden lassen. Referenzen ohne Beschreibung bleiben über die Autovervollständigung und direkte Verwendung verfügbar, werden Agenten aber nicht angeboten.

---

## Autovervollständigungseinträge ausblenden

Setzen Sie `hidden` auf `true`, um eine Referenz aus der `@`-Autovervollständigung in der TUI auszublenden.

```jsonc title="opencode.jsonc"
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}
```

`hidden` wirkt sich nur auf die Autovervollständigung aus. Eine ausgeblendete Referenz mit Beschreibung bleibt im Agentenkontext enthalten.

---

## Referenzen verwenden

Konfigurierte Referenzen erscheinen in der `@`-Autovervollständigung der TUI. Geben Sie `@alias` ein, um das Stammverzeichnis der Referenz anzuhängen, oder `@alias/`, um darin nach Dateien zu suchen.

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

Agenten erhalten in ihrem Systemkontext außerdem die aufgelösten Pfade und Beschreibungen konfigurierter Referenzen, die eine Beschreibung haben. So können sie eine Referenz untersuchen, wenn sie relevant ist, ohne dass Sie sie manuell anhängen müssen.

OpenCode erlaubt Referenzverzeichnisse automatisch über seine Berechtigungsgrenze für externe Verzeichnisse. Die normalen Tool-Berechtigungen gelten weiterhin; ein Agent, der keine Dateien bearbeiten darf, erhält zum Beispiel keinen Bearbeitungszugriff, nur weil ein Verzeichnis als Referenz konfiguriert ist.

---

## Felder konfigurieren

| Feld          | Lokal | Git  | Beschreibung                                                  |
| ------------- | ----- | ---- | ------------------------------------------------------------- |
| `path`        | Ja    | Nein | Lokales Referenzverzeichnis                                   |
| `repository`  | Nein  | Ja   | Git-URL, host/path oder GitHub-Wert `owner/repo`              |
| `branch`      | Nein  | Ja   | Optionaler Git-Branch oder Ref                                |
| `description` | Ja    | Ja   | Hinweis, wann die Referenz verwendet werden soll              |
| `hidden`      | Ja    | Ja   | Referenz aus der `@`-Autovervollständigung der TUI ausblenden |

Referenz-Aliase dürfen nicht leer sein und keine `/`, Leerzeichen, Backticks oder Kommas enthalten.