リファレンス

ローカルディレクトリやGitリポジトリをプロジェクトのリファレンスとして追加します。

リファレンスを使うと、OpenCodeは現在のプロジェクト外のディレクトリにアクセスできるようになります。作業中にドキュメント、共有ライブラリ、サンプル、または別のリポジトリを利用可能にするために使用します。

リファレンスは opencode.json または 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",
    },
  },
}

ローカルディレクトリ

ローカルディレクトリを参照するには path を使用します。

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

パスには次を指定できます。

• リファレンスを定義した設定ファイルからの相対パス
• /home/user/docs のような絶対パス
• ~/docs のようなホームディレクトリからの相対パス

文字列による省略記法も使用できます。

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

Gitリポジトリ

Gitリポジトリを参照するには repository を使用します。OpenCodeはリポジトリをローカルのリポジトリキャッシュに実体化し、チェックアウトしたソースをリファレンスディレクトリとして利用可能にします。

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

repository には Git の URL、host/path 形式の参照、GitHub の owner/repo 省略記法を指定できます。オプションの branch フィールドでブランチまたは ref を選択します。branch を指定しない場合、OpenCodeはリポジトリのデフォルトブランチを使用します。

ブランチや説明などのオプションが不要な場合は、文字列による省略記法を使用できます。

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

注記: Gitリファレンスは非同期で更新されます。新しく設定したリポジトリは、クローンや更新が完了するまで少し時間がかかる場合があります。

用途の説明

エージェントがリファレンスをいつ使用すべきかを説明するために description を追加します。

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

OpenCodeは、説明が設定されたリファレンスをエージェントのコンテキストに含めます。説明は、類似した内容のリファレンスを区別できるように、短く具体的にする必要があります。説明のないリファレンスはオートコンプリートや直接使用では引き続き利用可能ですが、エージェントには通知されません。

オートコンプリートへの表示を隠す

TUIの @ オートコンプリートからリファレンスを除外するには、hidden を true に設定します。

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

hidden はオートコンプリートにのみ影響します。説明が設定された非表示のリファレンスは、引き続きエージェントのコンテキストに含まれます。

リファレンスの使用

設定されたリファレンスはTUIの @ オートコンプリートに表示されます。@alias と入力するとリファレンスのルートを添付でき、@alias/ と入力するとその内部のファイルを検索できます。

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

エージェントは、説明が設定されたリファレンスの解決済みパスと説明もシステムコンテキストとして受け取るため、あなたが手動で添付しなくても、関連する場合にリファレンスを調べることができます。

OpenCodeは外部ディレクトリ権限の境界を通じて、リファレンスディレクトリを自動的に許可します。通常のツール権限は引き続き適用されます。例えば、ファイルを編集できないエージェントは、ディレクトリがリファレンスとして設定されていても編集権限を得ることはありません。

設定フィールド

リファレンスのエイリアスは空にすることはできず、/、空白、バッククォート、カンマを含めることもできません。