catapult-agent

CATAPULT ローカルエージェント — ローカル開発環境で GitHub Copilot CLI ジョブを実行する常駐デーモンです。

親プロジェクト: kakeru-ikeda/CATAPULT

概要

通常の CATAPULT はサーバー上でリポジトリを git clone した空の環境で動作するため、テスト実行・DB 接続・Docker Compose を使った動作確認などは実行できません。

catapult-agent をローカル PC にインストールして起動することで、既存の開発環境（.env・node_modules・起動済み Docker コンテナ）をそのまま使ってジョブを実行できます。

Slack/Discord でメンション
    ↓
CATAPULT サーバーがジョブを作成
    ↓
catapult-agent (ローカル PC) がジョブを受け取る
    ↓
ローカルリポジトリで Copilot CLI を実行
    ↓
結果をリアルタイムでスレッドに投稿

必要条件

• Node.js 22 以上
• GitHub Copilot CLI (npm install -g @github/copilot でインストール済み)
• CATAPULT サーバー（接続先として使用）

インストール

npm install -g catapult-agent

または npx で直接実行:

npx catapult-agent init

セットアップ

1. 初期化

catapult-agent init

対話形式で以下の情報を入力します:

| 入力項目 | 説明 | 例 | | ------------------------- | -------------------------------------------------------------------- | ---------------------------------- | | CATAPULT API サーバー URL | CATAPULT API サーバーのベース URL | https://api.catapult.example.com | | CATAPULT 管理画面 URL | ブラウザでアクセスする管理画面の URL | https://catapult.example.com | | マシン名 | Slack/Discord のモーダルで表示される識別名（省略で hostname を使用） | MacBook Pro | | ワークスペース親フォルダ | ローカルリポジトリが格納されているフォルダ | ~/projects | | JWT トークン | CATAPULT 管理画面からコピーした認証トークン | |

JWT トークンの取得方法:

1. CATAPULT 管理画面（フロントエンド）に Web ブラウザでアクセス（API サーバー URL ではない）
2. GitHub でログイン
3. ダッシュボード下部の "🔑 ローカルエージェント用トークン" カードでトークンをコピー

設定は ~/.catapult/config.json に保存されます。

2. 起動

catapult-agent start

エージェントが起動し、30 秒ごとにサーバーにハートビートを送信します。Slack/Discord でローカル実行を選択すると、このエージェントがジョブを受け取って実行します。

バックグラウンドで起動する場合

# pm2 を使う場合
npm install -g pm2
pm2 start catapult-agent -- start
pm2 save
pm2 startup

ワークスペースの解決

workspaceRoot 配下のディレクトリを再帰的にスキャンし、.git/config の remote.origin.url からジョブのリポジトリ（例: owner/repo）に一致するローカルパスを自動解決します。

例: workspaceRoot = ~/projects で owner/myapp のジョブが来た場合:

• ~/projects/myapp/.git/config の origin が github.com/owner/myapp に一致 → 実行パスとして使用

コマンド一覧

| コマンド | 説明 | | ----------------------- | ------------------------------------ | | catapult-agent init | 初期化・サーバーへのエージェント登録 | | catapult-agent start | エージェントデーモンを起動 | | catapult-agent --help | ヘルプを表示 |

設定ファイル

~/.catapult/config.json:

{
  "apiUrl": "https://catapult.example.com",
  "agentToken": "<エージェントトークン>",
  "name": "MacBook Pro",
  "workspaceRoot": "~/projects"
}

セキュリティ

• エージェントトークンはサーバー登録時に発行される一意のトークンです
• JWT トークンはサーバー登録にのみ使用され、設定ファイルには保存されません
• ジョブ実行時に使用する GitHub トークンはサーバーから暗号化された状態で受け取ります

ライセンス

MIT