2026-01-24 Ghostrunner APIサーバー plan

Ghostrunner APIサーバー 実装計画

1. 仕様サマリー

Ghostrunnerは、ローカルのClaude Code CLIを外部からAPI経由で操作するためのローカルAPIサーバー。スマホからTailscale経由でアクセスし、/plan カスタムコマンドを実行する機能を提供する（Phase 1）。

主要機能:

• POST /api/plan - Claude Codeの /plan コマンドを実行
• 静的ファイル配信 - シンプルUI（Phase 1）

フェーズ構成:

• Phase 1（今回）: シンプルUI + API基盤
• Phase 2（将来）: AI連携UI（OpenAI / Gemini Function Calling）

アーキテクチャ:

Loading diagram...

2. 変更ファイル一覧

3. 実装ステップ

Step 1: プロジェクト初期化

• 対象ファイル: go.mod
• 変更内容:
  • go mod init ghostrunner でモジュール初期化
  • github.com/gin-gonic/gin を追加

Step 2: Claude CLI実行サービス

• 対象ファイル: internal/service/claude.go
• 変更内容:
  • ClaudeService インターフェース定義（テスタビリティのため）
  • claudeServiceImpl 構造体
  • ExecutePlan(ctx context.Context, project, args string) (output string, err error) メソッド
  • exec.CommandContext で claude -p "/plan args" --cwd project を実行
  • stdout/stderr をキャプチャして返却
• 注意点: タイムアウト設定が必要（CLIは長時間実行される可能性）

Step 3: Plan ハンドラー

• 対象ファイル: internal/handler/plan.go
• 変更内容:
  • PlanRequest 構造体（Project, Args フィールド）
  • PlanResponse 構造体（Success, Output, Error フィールド）
  • PlanHandler 構造体（ClaudeService を DI）
  • Handle(c *gin.Context) メソッド - バリデーション、サービス呼び出し、レスポンス整形
• 注意点: project パスの検証（存在確認、パストラバーサル防止）

Step 4: メインエントリーポイント

• 対象ファイル: cmd/server/main.go
• 変更内容:
  • Gin エンジン初期化
  • 依存性の組み立て（ClaudeService -> PlanHandler）
  • ルーティング設定（POST /api/plan）
  • 静的ファイル配信（/ -> web/index.html）
  • :8080 でサーバー起動
• 注意点: graceful shutdown は Phase 2 で対応（最小構成のため）

Step 5: Function Calling UI

• 対象ファイル: web/index.html
• 変更内容:
  • プロジェクトパス入力フィールド
  • 引数（プロンプト）入力フィールド
  • 実行ボタン
  • 結果表示エリア（成功/エラー）
  • fetch で POST /api/plan を呼び出し
• 注意点: シンプルなバニラJS（フレームワーク不要）

4. 設計判断とトレードオフ

5. 懸念点と対応方針

5.1 要確認事項（実装前に解決が必要）

5.2 実装時の考慮事項

6. 確認事項（確定済み）

Q1: claude CLI のパス

• A) PATH上のclaudeを使用

Q2: プロジェクトパス制限

• A) 制限なし（Tailscale前提で信頼）

Q3: タイムアウト設定

• 60分（1時間）固定 - 長時間の作業に対応

Q4: CORS設定

• A) 無効（Tailscale経由で不要）

使用ツール

• Claude CLI (claude) - 公式CLIツール。-p フラグで非対話的実行

7. Phase 2: AI連携UI（将来計画）

Phase 1完成後、以下のAI連携機能を追加予定。

7.1 概要

OpenAI / Gemini のFunction Calling機能を使用し、AIとの会話の中でClaude Code APIを自動呼び出しする。

Loading diagram...

7.2 追加ファイル（Phase 2）

7.3 実装方針

1. クライアントサイド実装（推奨）

   • フロントエンドから直接OpenAI/Gemini APIを呼び出し
   • APIキーはブラウザのlocalStorageで管理（Tailscale閉域網前提）
   • Function定義でGhostrunner APIを指定

2. サーバーサイド実装（オプション）

   • GoサーバーでAI APIをプロキシ
   • APIキーをサーバー側で管理（より安全）

7.4 Function定義例

{
  "name": "execute_plan",
  "description": "Claude Codeの/planコマンドを実行して実装計画を作成する",
  "parameters": {
    "type": "object",
    "properties": {
      "project": {
        "type": "string",
        "description": "プロジェクトのパス"
      },
      "args": {
        "type": "string",
        "description": "計画作成の指示内容"
      }
    },
    "required": ["project", "args"]
  }
}

確認後、/go で実装を開始できます。

実装完了レポート

実装サマリー

• 実装日: 2026-01-24
• 変更ファイル数: 5 files
• Phase: Phase 1 (シンプルUI + API基盤)

変更ファイル一覧

計画からの変更点

実装計画に記載がなかった判断・選択:

• localStorage によるプロジェクトパス保存: UIの利便性向上のため、入力したプロジェクトパスをブラウザに保存する機能を追加
• ValidationError カスタム型: バリデーションエラーを明確に区別するためのエラー型を定義
• エラー時の output 返却: CLI実行エラー時にも途中出力を返却する仕様を採用（デバッグ容易性のため）

実装時の課題

ビルド・テストで苦戦した点

特になし

技術的に難しかった点

特になし

残存する懸念点

今後注意が必要な点:

• テストファイル未作成: Phase 1 ではテストファイルを作成していない。Phase 2 で対応予定
• Graceful Shutdown 未実装: 長時間実行中の CLI プロセスが強制終了される可能性がある
• 同時実行制限なし: 複数リクエストが同時に来た場合、リソース競合の可能性
• 認証なし: Tailscale 閉域網前提だが、追加のセキュリティ層があると望ましい

動作確認フロー

1. ターミナルで以下を実行:
   cd /Users/user/Ghostrunner
   go run ./cmd/server

2. ブラウザで http://localhost:8080 にアクセス

3. フォームに入力:
   - Project Path: /Users/user/Ghostrunner
   - Plan Arguments: 任意の計画指示

4. "Execute /plan" ボタンをクリック

5. 期待される動作:
   - ローディングスピナーが表示される
   - Claude CLI が実行される (数分かかる場合あり)
   - 成功時: 緑色の枠で出力結果が表示される
   - 失敗時: 赤色の枠でエラーメッセージが表示される

デプロイ後の確認事項

• claude コマンドが PATH に存在することを確認
• Tailscale 経由でスマホからアクセスできることを確認
• 長時間実行 (10分以上) が正常に完了することを確認
• プロジェクトパスの localStorage 保存が機能することを確認

レビュー結果

セキュリティ対策

コード品質

Phase 2 への引継ぎ事項

1. AI連携UI: OpenAI / Gemini Function Calling を使用したチャットUI
2. テスト追加: internal/service/claude_test.go, internal/handler/plan_test.go
3. Graceful Shutdown: signal.NotifyContext を使用した適切なシャットダウン処理
4. Health Check: /health エンドポイントの追加
5. 同時実行制限: セマフォによる並列実行数の制御

コードレビュー修正レポート (2026-01-24)

レビュー実施

go-reviewer エージェントによるコードレビューを実施。

修正内容

設計判断の維持（修正しなかった項目）

以下は計画書で意図的に決定された設計であり、修正しない:

検証結果

現在の実装状況

計画書の Phase 1 を超える機能が実装済み: