@cocorograph/hub-agent

Hub Hosted Cockpit のローカル常駐 agent。hub.cocorograph.com から outbound WSS で接続を受け、ローカルマシンの tmux / Claude Code セッションを Hub のブラウザ UI に中継する。

仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (Hub knowledge id=6080)

インストール

ワンライナー (推奨)

Hub Cockpit Agents ページ (https://hub.cocorograph.com/user/cockpit/agents) で 「ワンライナーセットアップ」をクリックして表示される curl コマンドをコピー → ターミナルで実行:

curl -fsSL https://api.hub.cocorograph.com/api/cockpit/agents/install-script | bash

このスクリプトは以下を 全自動 で実行します:

• Homebrew (macOS で無ければ install)
• tmux + node (Active LTS) + python3 (無ければ install)
• GNU coreutils の timeout (補助コマンド。macOS では brew で導入して gtimeout への symlink を ~/.local/bin に作成、Linux は存在確認のみで不在なら手動導入を案内。無くてもセットアップは続行)
• npm i -g @cocorograph/hub-agent
• npm i -g @anthropic-ai/claude-code / npm i -g @openai/codex (Claude Code / Codex CLI。既存なら更新)
• hub-agent enroll <token> (token は Hub session 経由で埋め込み済、5 分有効)
• hub-agent install-service で OS サービス登録

Windows (WSL2 方式)

Windows では WSL2 (Ubuntu) の中で hub-agent を動かします。Cockpit Agents ページで OS を Windows に切り替えると 管理者 PowerShell 用ワンライナーが表示されるので、 管理者として実行した PowerShell にコピペします:

$env:HUB_AGENT_TOKEN="<tok>"; $env:HUB_AGENT_URL="https://api.hub.cocorograph.com"; `
  irm https://unpkg.com/@cocorograph/hub-agent@latest/scripts/install.ps1 | iex

このスクリプトは WSL2 (Ubuntu-24.04) を導入 (要再起動 1 回・再起動後に自動再開)、 Ubuntu 初回ユーザーを無人作成 (Windows と同名 / パスワードなし / NOPASSWD sudo)、 WSL 内で既存 install.sh を実行、Task Scheduler でログオン時の常駐起動を登録します。

⚠️ 作業リポジトリは WSL 内 FS (/home/<user>/...) に置いてください。Windows ドライブ (/mnt/c/...) はファイル監視 (inotify) が WSL 跨ぎで不安定です。

詳細・設計判断は scripts/install.ps1 と docs/windows-installer-design.md を参照。

手動インストール (デバッグ用)

npm i -g @cocorograph/hub-agent
hub-agent enroll <token> --hub-url https://api.hub.cocorograph.com
hub-agent install-service

詳細は scripts/install.sh を参照。

CLI

hub-agent enroll <enrollment_token> [--hub-url URL] [--hostname NAME] [--force]
hub-agent start                       # 前景 daemon (install-service 不使用時)
hub-agent status                      # 現在の設定 + 接続状態
hub-agent stop                        # 停止方法のヒント表示
hub-agent install-service [--bin PATH]
hub-agent uninstall-service
hub-agent plugins list                # ~/.hub/plugins/ から読み込み済プラグイン
hub-agent plugins uninstall <name>    # ~/.hub/plugins/<prio>-<name>/ を削除

設定ファイル

• ~/.hub/agent.json — { agent_id, agent_token, hub_url } (chmod 600)
• ~/.hub/plugins/<prio>-<name>/plugin.mjs — プラグイン
• ~/.hub/plugins/<prio>-<name>/config.json — プラグイン個別設定
• ~/.hub/agent.log — install-service 経由起動時のログ
• ~/.hub/usage/latest.json — Claude Code statusLine cache (使用量集計の元データ、任意)

構成

チャット表示のマスク

Claude / Codex のチャットは、既定で表示・WebSocket 配信用コピーをマスクします。 get_skill_prompt、skill/・エージェント/ の内部本文取得、デプロイ接続情報取得の 結果を非表示にし、通常の本文・引数・エラー・差分に含まれる既知の秘密値も伏せます。 一般のナレッジ取得や通常のツール結果は表示します。

• 分割された秘密値の漏出を防ぐため、文字単位の途中出力ではなく完成済み本文を表示します。
• コード実行ラッパーに対象ツール名が明記されている場合、その実行結果全体を非表示にします。 動的に組み立てたツール名や、任意の文章に埋め込まれた未知形式の秘密を完全検出する機能ではありません。
• 許可確認には伏せた入力を渡し、変更されなかった伏せ字を元の入力へ戻して実行します。 一意に復元できない編集は拒否します。マスク失敗時に生の本文へ戻すことはしません。
• Codex のモデル入力・再開用 rollout 原本は変更しません。Claude の既存の終了後 JSONL マスクは継続します。ターミナル表示や過去に配信済みのデータを遡って消すものではありません。
• 緊急時の切り戻し設定 HUB_AGENT_TOOL_RESULT_MASK=0 は、秘密値を含め無加工で配信します。 通常運用では無効化しないでください。

hub-agent/
├── bin/
│   └── hub-agent.mjs          # CLI entry (commander)
├── src/
│   ├── main.mjs               # daemon 本体 + dispatcher
│   ├── config.mjs             # ~/.hub/agent.json 管理
│   ├── enroll.mjs             # enrollment フロー
│   ├── ws-client.mjs          # outbound WSS + reconnect with jitter
│   ├── claude-stream-bridge.mjs # Claude Agent SDK チャット中継
│   ├── codex-stream-bridge.mjs  # Codex app-server チャット中継
│   ├── tmux.mjs               # tmux list/create/kill
│   ├── state.mjs              # session status / context_pct 検知
│   ├── skills.mjs             # ~/.claude/skills 集計
│   ├── usage.mjs              # Claude Code 使用量集計
│   ├── plugin-loader.mjs      # plugin discovery + hook chain
│   ├── hooks.mjs              # hook 名・型定義
│   └── service-install.mjs    # launchd / systemd install
├── templates/
│   ├── co.cocorograph.hub-agent.plist
│   └── hub-agent.service
├── scripts/
│   ├── install.sh             # ワンライナーセットアップ (macOS / Linux / WSL)
│   └── install.ps1            # Windows (WSL2 導入 + Task Scheduler 登録)
└── test/

開発状況

• [x] Sprint A: 仕様書 (Hub knowledge id=6080)
• [x] Sprint B: Hub 側 enrollment API + WS endpoint 雛形
• [x] Sprint C: 本リポジトリの雛形 + outbound WSS + hook system
• [x] Sprint E: tmux exec/list/create/kill 移植 + auto list UI
• [x] Sprint F: Hub Browser↔Agent multiplex 中継
• [x] Sprint G: Hub frontend /user/cockpit/{agents,terminal} ページ
• [x] Sprint H: skills / state dot / usage badge リレー
• [x] Sprint I: 接続復旧 (jitter + force reconnect + Celery stale 検知)
• [x] Sprint J: 本リポジトリ publish 準備 + launchd/systemd 連携

プラグイン

プラグインは利用者が ~/.hub/plugins/<prio>-<name>/plugin.mjs を自分で置く運用です。 置けば plugins list から読み込まれ、plugins uninstall <prio>-<name> で削除できます。

リポジトリ同梱の example プラグインはありません。唯一同梱していた plugins/10-tailscale-remote/ は pty spawn を横取りするプラグインで、pty 中継の撤去と 同時に削除しました。同梱 example が 0 件になったため、それを配る plugins examples / plugins install と package.json の files の plugins/ も外しています。

ライセンス

UNLICENSED. Cocorograph Inc. 社内専用。