参照

参照を使用すると、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、ホスト/パス形式の参照、GitHub の owner/repo 省略形を指定できます。オプションの branch フィールドでブランチまたは ref を選択します。branch を指定しない場合、OpenCode はリポジトリのデフォルトブランチを使用します。

ブランチ、説明、その他のオプションが不要な場合は、文字列の省略形を使用できます。

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

用途の説明

エージェントが参照を使用するタイミングを説明するには、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 は、外部ディレクトリの権限境界において参照ディレクトリを自動的に許可します。通常のツール権限は引き続き適用されます。たとえば、ファイルを編集できないエージェントは、ディレクトリが参照として設定されていても編集権限を得ることはありません。

設定フィールド

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