リファレンス

opencode.json のトップレベルにある references キーは、現在のプロジェクト外のリソースをマウントしてエイリアスを付けます。ローカルディレクトリには path（相対パス・絶対パス・~/）、Git リポジトリには repository（Git URL、host/path、GitHub の owner/repo 略記、オプションの branch）を使用します。description を追加するとエージェントが各参照をいつ適用すべきか判断できます。"hidden": true を設定すると TUI の @ 自動補完からは外れますが、コンテキストへの供給は続きます。@エイリアス で添付し、@エイリアス/ で閲覧します。参照先のパスは自動的に外部ディレクトリの権限境界を越えますが、通常のツール権限は引き続き適用されます。

参照（reference）により、OpenCode は現在のプロジェクト外のディレクトリにアクセスできます。各参照にはエイリアスが割り当てられ、その内容を会話に添付するために使用できます。

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "製品機能に関する質問に答えるときに使用"
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "SDK を使ったコードを実装するときに使用"
    }
  }
}

ローカルディレクトリ

path フィールドでローカルディレクトリを参照します。相対パスはプロジェクトルートを基準に解決され、絶対パスはそのまま使用され、~/ で始まるパスはホームディレクトリに解決されます：

{
  "references": {
    "shared": { "path": "~/projects/shared-libs" }
  }
}

追加のオプションが必要ない場合は、単なる文字列が path の省略表現になります：

{
  "references": {
    "shared": "~/projects/shared-libs"
  }
}

Git リポジトリ

repository フィールドで Git リポジトリを参照します。完全な Git URL、host/path 形式、GitHub の owner/repo 略記のいずれも使用できます。リポジトリは非同期で更新されるキャッシュにクローンされるため、参照は常に最新に保たれます：

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

branch フィールドはブランチまたは ref を選択します。省略した場合はデフォルトブランチが使用されます。ローカルディレクトリと同様に、branch が不要な場合は文字列値が省略表現になります。

用途の説明

description を追加して、各参照の用途や参照すべきタイミングをエージェントに伝えます。説明のない参照は、エージェントに自発的に提示されることはありません：

{
  "references": {
    "design-system": {
      "path": "../design-tokens",
      "description": "UI コンポーネントやデザイントークンを実装するときに使用"
    }
  }
}

自動補完項目の非表示

"hidden": true を設定すると、その参照は TUI の @ 自動補完メニューに表示されなくなります。説明付きの非表示の参照も、引き続きエージェントのコンテキストに含まれます：

{
  "references": {
    "archive": {
      "path": "../legacy-archive",
      "description": "移行作業のための歴史的経緯",
      "hidden": true
    }
  }
}

参照の使用

TUI では、@ に続けてエイリアスを入力すると参照の内容をメッセージに添付でき、@エイリアス/ で中のファイルをあいまい検索できます。関連するショートカットはキーバインドを参照してください。

参照されたディレクトリは権限で説明されている外部ディレクトリ権限境界を自動的に越えるため、ツールは追加の承認なしで読み取れます。通常のツールレベルの権限ルールも引き続き適用されます。

設定フィールド

フィールド	ローカル	Git	説明
`path`	✓		参照するローカルディレクトリ
`repository`		✓	Git URL、`host/path`、または `owner/repo`
`branch`		✓	任意のブランチまたは ref。省略時は既定ブランチ
`description`	✓	✓	この参照をいつ使うかに関するエージェントへのガイダンス
`hidden`	✓	✓	TUI の `@` 自動補完から除外

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