@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 20+ (無ければ install)
• npm i -g @cocorograph/hub-agent
• hub-agent enroll <token> (token は Hub session 経由で埋め込み済、5 分有効)
• hub-agent install-service で OS サービス登録

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

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 examples            # repo 同梱の install 可能 example
hub-agent plugins install <name> [--force]
hub-agent plugins uninstall <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 (使用量集計の元データ、任意)

構成

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
│   ├── pty-bridge.mjs         # node-pty 多重化
│   ├── tmux.mjs               # tmux exec/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/
│   └── fix-node-pty-perms.mjs # node-pty spawn-helper +x 修復 (postinstall)
└── 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 D: pty bridge
• [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 連携
• [x] Sprint K: remote-ops プラグイン例 (plugins/10-tailscale-remote/)

同梱プラグイン

• plugins/10-tailscale-remote — 自宅 Mac (hub-agent host) を会社 Mac (remote_host) の tmux に対する透過プロキシ化。 hub-agent plugins install 10-tailscale-remote で ~/.hub/plugins/ にコピー、 config.json を編集して restart で有効化

ライセンス

UNLICENSED. Cocorograph Inc. 社内専用。