インストール
前提条件
- Claude Code — CLIがインストール済みであること
- jq — フックスクリプトに必要（macOSでは
brew install jq） - Go — ローカル開発ビルドにのみ必要（プラグインインストールでは不要）
プラグインインストール（推奨）
プラグインをインストールすると、すべてが自動的に設定されます：
bash
# マーケットプレイスを登録（初回のみ）
/plugin marketplace add hiromaily/claude-forge
# プラグインをインストール
/plugin install claude-forge
/reload-pluginsインストール後、Claude Codeを再起動して確認：
bash
/mcp # forge-state が Connected と表示されるはず自動的に行われること
プラグインがインストールされると、Claude Codeは：
- MCPサーバーを登録 —
.mcp.jsonがforge-stateサーバーを宣言 - Setupフックを実行 — GitHub Releasesからビルド済み
forge-state-mcpバイナリをダウンロード - ソースビルドにフォールバック — リリースバイナリが利用不可の場合、
go buildでソースからビルド
plugin.json ← "mcpServers": "./.mcp.json" を宣言
└─> .mcp.json ← forge-state サーバー定義（stdioトランスポート）
└─> scripts/launch-mcp.sh ← 自己修復ランチャー
└─> bin/forge-state-mcp ← Setupフックでダウンロードされたバイナリ代替インストール方法
bash
# ローカルクローンからインストール
claude plugins install ~/path/to/claude-forge
# ワンタイムセッション（永続インストールなし）
claude --plugin-dir ~/path/to/claude-forgeローカル開発セットアップ
claude-forge自体の開発に携わるコントリビューター向け：
bash
# バイナリをビルド・インストールし、Claude Codeに登録
make setup-manual--scope local でMCPサーバーが登録されます（.claude/settings.local.json に書き込み、gitignore済み）。
環境変数
| 変数 | 必須 | 説明 |
|---|---|---|
FORGE_AGENTS_PATH | はい | agents/ ディレクトリの絶対パス。make setup で自動設定。 |
FORGE_SPECS_DIR | いいえ | デフォルトの .specs/ ディレクトリを上書き。 |
FORGE_EVENTS_PORT | いいえ | SSE イベントエンドポイントおよび同梱 Web ダッシュボード用ポート。デフォルト 8099（.mcp.json で自動設定）。競合時は 8100〜8200 にフォールバック。 |
トラブルシューティング
forge-state が2つ表示され、1つが失敗
claude-forge開発リポジトリ内でプラグインもインストールされている場合、make setup-manual を実行してローカルスコープのオーバーライドを登録してください。
forge-state が "Failed to connect" と表示
- バイナリの存在を確認
FORGE_AGENTS_PATHが有効なディレクトリを指していることを確認- バイナリを直接テスト：
echo '{}' | forge-state-mcp - セットアップを再実行
Setupフックが実行されなかった
バージョンマーカーを削除して再ダウンロードをトリガー：
bash
rm -f $(claude plugins path)/claude-forge/bin/.installed-versionアップデート
bash
claude plugin update claude-forge@claude-forge
/reload-plugins
# MCPサーバーをリロードするにはClaude Codeを再起動アンインストール
bash
claude plugins uninstall claude-forge@claude-forge
# 手動登録した場合：
claude mcp remove forge-state -s user