ref-macker

ref-macker — macker 操作リファレンス

macker は tailnet 上の複数マシンの tmux セッションを一元管理する薄いコントロールプレーン。 各ノードに常駐 agent (HTTP :4477)、hub に collector (HTTP :4478、イベント集約+共有ストレージ)、 hub の Web dashboard (:4490) が載る。CLI は macker 一発でどのマシンからでも同じに使える。

主要コマンド

macker ls                         # 全ノードとセッションの一覧 (self に * 印)
macker <node>                     # そのノードに新規セッションを開く (窓を閉じればそのセッションだけ死ぬ)
macker <node>:<session>           # 名前付きセッションに attach (無ければ作る、再 attach 可)
macker <node> <session>           # 同上 (スペース区切り)
macker <node> <index>             # `macker <node> ls` の番号で attach (orphaned → detached → attached の順)
macker <node> ls                  # 1 ノードのセッション詳細 (state/age/command — clear 判断用)
macker <node>[:<session>] clear   # セッションをリセット (kill して次回 attach は新規)
macker exec <node> -- <cmd>...    # 認可済みコマンドをリモート実行 (stdout/stderr/exit code が返る)
macker usage [node]               # Claude/Codex のサインイン アカウントと残量 (5h/週次ウィンドウ)
macker grid <target>...           # 複数ターゲットを格子で同時 attach
macker storage <ls|put|get|cat|rm>  # hub 共有ストレージ (詳細は ref-macker-storage)
macker context [ls|use <name>]    # 複数 tailnet (コンテキスト) の切替
macker agent / macker collector   # デーモンの手動起動 (常用は LaunchAgent)

ターゲット記法

• <node> … tailnet ノード名。前方一致のユニーク短縮可 (kyohei → kyoheimac-mini)。self/local/空 = 自マシン
• <node>:<session> … 特定セッション。数字だけの名前は index と解釈されるので避ける
• グローバルフラグ --context <name> (または MACKER_CONTEXT) でコンテキスト切替

よくある操作レシピ

# リモートで claude を動かす定番: 名前付きセッションを立てて attach
macker mbp-5:work             # 切断してもセッションは生きる。再実行で再 attach

# 状態確認 → 片付け
macker mbp-5 ls               # orphaned (持ち主が消えた) が上に出る
macker mbp-5:dead-one clear   # orphaned はこれで掃除

# リモートでワンショットコマンド
macker exec mbp-5 -- git -C ~/repo pull

# AI 残量の横断確認 (codexbar キャッシュ。--refresh は分単位かかる)
macker usage

Dashboard

hub の http://<hub-tailnet-ip>:4490 — PC 用フル画面 (ノード/セッション/ウォッチ/イベント/残量)。 /m がスマホアプリ UI (PWA)、/storage が共有ストレージブラウザ。 GUI の kill/send/peek は agent API への中継で、認可は Tailscale identity。

注意 (運用知見)

• 稼働中の Claude Code TUI セッションへ tmux send-keys で直接キーを送らない — Enter/矢印は コンテキスト依存で誤爆する。連絡やタスク投入はワンショットの macker exec か issue トラッカーで。
• agent が落ちているノードは macker ls で (agent?) と出る。macker リポジトリ内なら macker-join (新規参加) / macker-collector-retarget (ハブ切替) の project skill が使える。
• 認可は Tailscale identity + ポリシー (owners / exec_allow / attach_allow)。exec が 403 なら そのノードの config (~/.config/macker/config.json) の policy に自分の login を足す。