OpenCodeプラグインのインストール

この章で学べること

OpenCodeでPlannotatorプラグインをインストールする
submit_planツールと/plannotator-reviewコマンドを設定する
環境変数を設定する（リモートモード、ポート、ブラウザなど）
プラグインのインストールが成功したか確認する

現在の課題

OpenCodeでAI Agentを使用する際、プランレビューはターミナルでプレーンテキストを読む必要があり、正確なフィードバックが困難です。プランにアノテーションを付けたり、コメントを追加したりできるビジュアルインターフェースが欲しい。そして、フィードバックを構造化してAgentに自動送信したい。

このチュートリアルが役立つ場面

Plannotatorを使い始める前の必須ステップ：OpenCode環境で開発しており、インタラクティブなプランレビュー体験を求めている場合。

🎒 始める前の準備

[ ] OpenCodeがインストール済み
[ ] 基本的なopencode.json設定（OpenCodeプラグインシステム）を理解している

前提知識

OpenCodeの基本操作をまだ理解していない場合は、先にOpenCode公式ドキュメントを参照することをお勧めします。

コアコンセプト

PlannotatorはOpenCodeに2つのコア機能を提供します：

submit_planツール - Agentがプランを完了した際に呼び出し、ブラウザでインタラクティブレビューを開く
/plannotator-reviewコマンド - 手動でGit diffコードレビューをトリガー

インストールは2ステップに分かれます：

opencode.jsonにプラグイン設定を追加（submit_planツールを有効化）
インストールスクリプトを実行（/plannotator-reviewコマンドを取得）

ステップバイステップ

ステップ1：opencode.jsonでプラグインをインストール

OpenCodeの設定ファイル（通常はプロジェクトルートまたはユーザー設定ディレクトリにあります）を見つけ、plugin配列にPlannotatorを追加します：

json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}

理由opencode.jsonはOpenCodeのプラグイン設定ファイルです。プラグイン名を追加すると、OpenCodeが自動的にnpmリポジトリからダウンロードして読み込みます。

期待される結果：OpenCode起動時に「Loading plugin: @plannotator/opencode...」というメッセージが表示されます。

ステップ2：OpenCodeを再起動

理由プラグイン設定の変更後は、再起動しないと反映されません。

期待される結果：OpenCodeがすべてのプラグインを再読み込みします。

ステップ3：インストールスクリプトでスラッシュコマンドを取得

macOS / Linux / WSLWindows PowerShell

bash

curl -fsSL https://plannotator.ai/install.sh | bash

powershell

irm https://plannotator.ai/install.ps1 | iex

理由このスクリプトは以下を実行します：

plannotator CLIツールをシステムにダウンロード
/plannotator-reviewスラッシュコマンドをOpenCodeにインストール
キャッシュされたプラグインバージョンをクリーンアップ

期待される結果：インストール成功メッセージが表示されます（例：「Plannotator installed successfully!」）。

ステップ4：インストールの確認

OpenCodeでプラグインが正常に動作しているか確認します：

submit_planツールが利用可能か確認：

会話でAgentに「submit_planを使ってプランを提出してください」と依頼
プラグインが正常であれば、Agentはこのツールを認識して呼び出せるはず

/plannotator-reviewコマンドが利用可能か確認：

入力欄に/plannotator-reviewと入力
プラグインが正常であれば、コマンド候補が表示されるはず

期待される結果：両方の機能がエラーなく正常に使用できます。

ステップ5：環境変数の設定（オプション）

Plannotatorは以下の環境変数をサポートしています。必要に応じて設定してください：

環境変数の説明

環境変数	用途	デフォルト値	例
`PLANNOTATOR_REMOTE`	リモートモードを有効化（devcontainer/SSH）	未設定	`export PLANNOTATOR_REMOTE=1`
`PLANNOTATOR_PORT`	固定ポート（リモートモードでは必須）	ローカルはランダム、リモートは19432	`export PLANNOTATOR_PORT=9999`
`PLANNOTATOR_BROWSER`	カスタムブラウザパス	システムデフォルト	`export PLANNOTATOR_BROWSER="/Applications/Google Chrome.app"`
`PLANNOTATOR_SHARE`	URL共有を無効化	有効	`export PLANNOTATOR_SHARE=disabled`

リモートモード設定例（devcontainer/SSH）：

.devcontainer/devcontainer.jsonに以下を追加：

json

{
  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },
  "forwardPorts": [9999]
}

理由

リモートモード：コンテナやリモートマシンでOpenCodeを実行する際、固定ポートを使用してブラウザを自動的に開く
ポートフォワーディング：ホストマシンからコンテナ内のサービスにアクセス可能にする

期待される結果：Agentがsubmit_planを呼び出すと、コンソールにサーバーURLが表示されます（ブラウザが自動的に開く代わりに）：

Plannotator server running at http://localhost:9999

ステップ6：OpenCodeを再起動（環境変数を変更した場合）

ステップ5で環境変数を設定した場合は、再度OpenCodeを再起動して設定を反映させる必要があります。

チェックポイント ✅

インストール完了後、以下を確認してください：

[ ] opencode.jsonに@plannotator/opencode@latestが追加されている
[ ] OpenCode再起動後、プラグイン読み込みエラーがない
[ ] /plannotator-reviewと入力するとコマンド候補が表示される
[ ] （オプション）環境変数が正しく設定されている

よくあるトラブルと解決策

よくあるエラー1：プラグインの読み込みに失敗

症状：OpenCode起動時に「Failed to load plugin @plannotator/opencode」と表示される

考えられる原因：

ネットワークの問題でnpmからダウンロードできない
npmキャッシュが破損している

解決方法：

ネットワーク接続を確認
インストールスクリプトを実行（プラグインキャッシュをクリーンアップ）
npmキャッシュを手動でクリア：npm cache clean --force

よくあるエラー2：スラッシュコマンドが利用できない

症状：/plannotator-reviewと入力してもコマンド候補が表示されない

考えられる原因：インストールスクリプトが正常に実行されていない

解決方法：インストールスクリプトを再実行（ステップ3）

よくあるエラー3：リモートモードでブラウザが開かない

症状：devcontainerでsubmit_planを呼び出してもブラウザが開かない

考えられる原因：

PLANNOTATOR_REMOTE=1が設定されていない
ポートフォワーディングが設定されていない

解決方法：

PLANNOTATOR_REMOTE=1が設定されていることを確認
.devcontainer/devcontainer.jsonのforwardPortsに設定したポートが含まれているか確認
表示されたURLに手動でアクセス：http://localhost:9999

よくあるエラー4：ポートが使用中

症状：サーバー起動に失敗し、「Port already in use」と表示される

考えられる原因：以前のサーバーが正しく終了していない

解決方法：

PLANNOTATOR_PORTを別のポートに変更
または、ポートを使用しているプロセスを手動で終了（macOS/Linux: lsof -ti:9999 | xargs kill）

この章のまとめ

この章では、OpenCodeでPlannotatorプラグインをインストールして設定する方法を学びました：

opencode.jsonでプラグインを追加 - submit_planツールを有効化
インストールスクリプトを実行 - /plannotator-reviewスラッシュコマンドを取得
環境変数を設定 - リモートモードやカスタム要件に対応
インストールを確認 - プラグインが正常に動作していることを確認

インストール完了後、以下が可能になります：

Agentにsubmit_planを使ってプランを提出させ、インタラクティブレビューを実行
/plannotator-reviewを使って手動でGit diffをレビュー

次の章の予告

次の章では**プランレビューの基本**を学びます。
学べる内容：
AIが生成したプランの確認方法
様々なタイプのアノテーション（削除、置換、挿入、コメント）の追加
プランの承認または却下

付録：ソースコード参照

クリックしてソースコードの場所を表示

更新日：2026-01-24

機能	ファイルパス	行番号
プラグインエントリ定義	`apps/opencode-plugin/index.ts`	34-280
`submit_plan`ツール定義	`apps/opencode-plugin/index.ts`	209-252
---	---	---
プラグイン設定（opencode.json）注入	`apps/opencode-plugin/index.ts`	55-63
環境変数の読み取り	`apps/opencode-plugin/index.ts`	37-51
プランレビューサーバー起動	`packages/server/index.ts`	全文
コードレビューサーバー起動	`packages/server/review.ts`	全文
リモートモード検出	`packages/server/remote.ts`	全文

主要な定数：

PLANNOTATOR_REMOTE: リモートモードフラグ（「1」または「true」で有効化）
PLANNOTATOR_PORT: 固定ポート番号（ローカルはデフォルトでランダム、リモートはデフォルトで19432）

主要な関数：

startPlannotatorServer(): プランレビューサーバーを起動
startReviewServer(): コードレビューサーバーを起動
getSharingEnabled(): URL共有スイッチの状態を取得（OpenCode設定または環境変数から）

5分でクイックスタート

AIプランとコードのレビュー

チームコラボ+ノート保存

問題が発生したら

OpenCodeプラグインのインストール

この章で学べること

現在の課題

このチュートリアルが役立つ場面

🎒 始める前の準備

コアコンセプト

ステップバイステップ

ステップ1：opencode.jsonでプラグインをインストール

ステップ2：OpenCodeを再起動

ステップ3：インストールスクリプトでスラッシュコマンドを取得

ステップ4：インストールの確認

ステップ5：環境変数の設定（オプション）

ステップ6：OpenCodeを再起動（環境変数を変更した場合）

チェックポイント ✅

よくあるトラブルと解決策

よくあるエラー1：プラグインの読み込みに失敗

よくあるエラー2：スラッシュコマンドが利用できない

よくあるエラー3：リモートモードでブラウザが開かない

よくあるエラー4：ポートが使用中

この章のまとめ

次の章の予告

付録：ソースコード参照

OpenCodeプラグインのインストール ​

この章で学べること ​

現在の課題 ​

このチュートリアルが役立つ場面 ​

🎒 始める前の準備 ​

コアコンセプト ​

ステップバイステップ ​

ステップ1：opencode.jsonでプラグインをインストール ​

ステップ2：OpenCodeを再起動 ​

ステップ3：インストールスクリプトでスラッシュコマンドを取得 ​

ステップ4：インストールの確認 ​

ステップ5：環境変数の設定（オプション） ​

ステップ6：OpenCodeを再起動（環境変数を変更した場合） ​

チェックポイント ✅ ​

よくあるトラブルと解決策 ​

よくあるエラー1：プラグインの読み込みに失敗 ​

よくあるエラー2：スラッシュコマンドが利用できない ​

よくあるエラー3：リモートモードでブラウザが開かない ​

よくあるエラー4：ポートが使用中 ​

この章のまとめ ​

次の章の予告 ​

付録：ソースコード参照 ​

OpenCodeプラグインのインストール

この章で学べること

現在の課題

このチュートリアルが役立つ場面

🎒 始める前の準備

コアコンセプト

ステップバイステップ

ステップ1：opencode.jsonでプラグインをインストール

ステップ2：OpenCodeを再起動

ステップ3：インストールスクリプトでスラッシュコマンドを取得

ステップ4：インストールの確認

ステップ5：環境変数の設定（オプション）

ステップ6：OpenCodeを再起動（環境変数を変更した場合）

チェックポイント ✅

よくあるトラブルと解決策

よくあるエラー1：プラグインの読み込みに失敗

よくあるエラー2：スラッシュコマンドが利用できない

よくあるエラー3：リモートモードでブラウザが開かない

よくあるエラー4：ポートが使用中

この章のまとめ

次の章の予告

付録：ソースコード参照