マルチプレクサ

Collieはインストールごとに1つのマルチプレクサ（Herdr、tmux、またはzellij）を操作します。デフォルトはHerdrです。このページでは、Collieをこれら3つのいずれかに向ける方法、各バックエンドが応答できる内容、ペイン内のエージェントを検出するためにCollieが使用するビーコンについて説明します。

Collieをマルチプレクサに向ける

COLLIE_MUX でバックエンドを指定し、エンドポイントを設定して再起動し、beacon フックをインストールします。

1.0 では実験的機能です。 tmuxとzellijは単一ホスト上のtmux 3.6bおよびzellij 0.44.2でテストされています。デフォルトかつ主要なサポート対象バックエンドはHerdrです。テスター募集:使用しているマルチプレクサ、バージョン、OS、発生した事象を記載し、tmux: …またはzellij: …というタイトルでAltanS/collieにIssueを作成してください。

コマンドラインでマルチプレクサを指定します:

COLLIE_MUX=herdr collie start
COLLIE_MUX=tmux collie start
COLLIE_MUX=zellij collie start

デフォルトのターゲットと異なる場合は、エンドポイントを設定します:

# in your .env: ~/.config/collie/.env, or Herdr's plugin config dir on a Herdr
# install. See Configure for the full precedence.
COLLIE_MUX=tmux
COLLIE_MUX_ENDPOINT_TMUX=/run/user/1000/collie-tmux.sock
COLLIE_MUX_ENDPOINT_ZELLIJ=collie-zellij

# only if the binary sits somewhere unusual
# COLLIE_TMUX_BIN=/usr/bin/tmux
# COLLIE_ZELLIJ_BIN=/home/you/.local/bin/zellij

Herdr にはここに対応するエンドポイント変数がありません。そのソケットは HERDR_SOCKET_PATH であり、COLLIE_MUX_ENDPOINT_ 名ではありません。

そのソケットはローカル専用です。Herdr 0.9.0ではSSHマシンを保存して1つのHerdrクライアントに複数のサーバーを表示できますが、Collieはいずれも読み取りません。そのため、Herdrに保存されたマシンはpackメンバーにはなりません。別のマシンのセッションをスマートフォンに表示できるのは、Collieのpackのみです。

その後、再起動し、ビーコンフックをインストールして、スマートフォンから認識できる場所でエージェントを起動します:

collie restart                 # after every .env edit
collie hooks install claude    # once per host, tmux and zellij only

# open a window or a tab for the agent
tmux -S /run/user/1000/collie-tmux.sock new-window -n claude
zellij --session collie-zellij action new-tab --name claude

claude                         # in that window or tab

上記コマンドの処理内容

コマンドラインで COLLIE_MUX を指定すると、その実行時およびそれ以降のすべての実行時の選択が設定されます。start は .env に名前を書き込むため、後で collie start を実行しても同じマルチプレクサを操作します。

COLLIE_MUX が未設定の場合、start は Herdr、tmux、zellij を検出し、バックエンドの選択を促して、その回答を .env に書き込みます。設定のリファレンス全体については MUX_CONTRACT.md → Collie からマルチプレクサを指定する を参照してください。

collie hooks install claude は、tmux および zellij で必要となる Collie の beacon フックをインストールします。これらはペインを汎用シェルとして公開するため、フックがないとすべてのペインが bash として表示されます。

このコマンドは ~/.claude/settings.json を更新し、プロジェクト設定（詳細は以下を参照）には変更を加えません。実行中の Claude インスタンスは設定を再読み込みしないため、再起動してください。

注。 このモードでは Herdr は不要です。COLLIE_MUX=tmux または COLLIE_MUX=zellij を指定すると、ブリッジは選択されたアダプターのみを読み込み、Herdr のソケットを無視します。Herdr 設定ルートをまたぐマルチセッション検出は無効になります（bridge/index.ts）。Herdr をインストールまたは実行しておく必要はなく、.env はプラグイン設定ディレクトリではなく ~/.config/collie/ に配置されます。

tmuxに関する注意事項

COLLIE_TMUX_BINは通常、未設定のままにします。Collieは標準パスのリストを確認し、バックグラウンドサービスやHerdrのアクションがログインシェルと共有しないPATHは読み取りません。

注。 ソケットパスは短く保ってください。約 100 文字を超える Unix ドメインソケットは接続に失敗し、tmux は error connecting to … (File name too long) を返します。深いディレクトリパスではなく、/run/user/<uid>/ または /tmp を使用してください。

window-size を manual に設定した 3.7 未満の tmux バージョンでは、ウィンドウを作成するとサーバーがクラッシュします。Collie はこの状態でのウィンドウ作成をブロックし、tmux set -g window-size latest の実行を促します。テスト済みのバージョン一覧は 要件 に記載されています。

zellijに関する注意事項

利用中のディストリビューションに zellij パッケージがない場合は、zellij の GitHub リリース からバイナリをダウンロードして PATH に配置してください。

エンドポイントを空のままにすると、実行中の単一セッションがデフォルトになります。セッションが存在しないか複数存在する場合、Collie は 1 つを選択せずにエラーで停止します。名前付きセッションが終了した場合、Collie はアクティブなセッションに切り替えるのではなく、そのセッション名を報告します。

Zellij がセッションを検出するには XDG_RUNTIME_DIR が必要です。Collie がすべてのセッションを終了済みとして報告する場合は、systemd サービスにこの環境変数が含まれていることを確認してください（コントラクト）。

Zellij セッションは、最初のターミナルとは独立して維持されます。zellij -s collie-zellij でセッションを作成し、Ctrl o d でデタッチします。ヘッドレスホストでは、zellij attach --create-background collie-zellij でデタッチされたセッションを直接開始できます（zellij 0.44.2 で検証済み）。

注。 Collie はアクティブなセッションを管理しますが、セッションの作成や再起動は行いません。

動作確認

collie doctor   # the `mux` check names the multiplexer, its endpoint,
                # and whether it answered

# `[bridge] mux: tmux · socket /run/user/1000/collie-tmux.sock`, printed at
# startup; a multiplexer it cannot reach is one warning line more
collie logs

# the herd, as the phone is given it
curl -s http://127.0.0.1:8787/api/snapshot | head -c 400

この curl 呼び出しは認証ヘッダーなしで機能します。COLLIE_DEVICE_HEADER が有効な場合でも、読み取りリクエストはデバイス検証をバイパスします（設定）。設定されたヘッダーが必要なのは書き込みアクションのみです。

スマートフォンの UI を確認します。ダッシュボードに tmux ウィンドウ または zellij タブ が表示され、Claude ペインが bash ではなくエージェントとして識別されている必要があります。ペインが依然として標準シェルとして表示される場合は、以下の beacon フックのインストール手順を確認してください。

Collie は Claude 自身の設定にフックを書き込みます

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

tmux と zellij はペインを汎用シェルとして公開するため、エージェント側から自身を通知する必要があります。これには、Claude Code の設定に Collie の beacon フックをインストールする必要があります。

出力は、このリポジトリの bin/collie パスを参照します。パッケージインストールでは、バージョン管理されたディレクトリではなく、インストールされたバイナリパス（~/.local/bin/collie または ~/.local/share/collie/current/bin/collie）が使用されるため、アップデート後もリンクが有効なまま維持されます。

Claude 設定変更時の動作詳細:

• —
  グローバル の ~/.claude/settings.json およびアクティブな CLAUDE_CONFIG_DIR を変更します。プロジェクトレベルの .claude/settings.json ファイルには変更を加えません。
• —
  # collie-beacon v1 のタグが付いた、タイムアウト10秒の 5つ フックを注入します。既存のフックは保持されます。hooks uninstall claude は Collie のエントリのみを削除します。
• —
  実行中の Claude プロセスは設定を再読み込みしません。 変更を適用するにはエージェントを再起動してください。
• —
  Linux のみ。 エージェントの生存確認は /proc に依存しています。他の OS ではビーコンが送信されません。
• —
  ビーコンはマルチプレクサごとに固有です。 これらはアクティブなバックエンドのペイン識別子とセッション識別子を記録します。COLLIE_MUX を切り替えると既存のビーコンは無効になります。古いビーコンは消去されるまでディスク上に残り、collie doctor の beacons カウントに表示されます。
• —
  COLLIE_STATE_DIR を使用する場合は、エージェントのシェル環境でエクスポートしてください。collie beacon emit はこの変数を直接読み取ります。設定しない場合、ビーコンはデフォルトの状態ディレクトリに書き込まれ、ブリッジから検出できなくなります。

collie doctor には、フックの不足や移動したチェックアウトへの無効なパスを指摘する beacon-hooks-claude 診断チェックが含まれています。ランタイムの詳細については、エージェントビーコン を参照してください。

Herdr との変更点

以下の表に主な違いをまとめています。正確な仕様については MUX_CONTRACT.md を参照してください。

アクティブなビーコンがない場合、tmux と zellij はペインを生のシェルとして表示します。ペイン履歴は空のコンテンツを返すのではなく、利用不可として扱われます。

スマートフォン利用時の2つの相違点

• —
  "N秒前に同期": このインジケーターはダッシュボードのヘッダーに表示され、データの経過時間を示します。zellij などのように、バックエンドが定期ポーリングに依存している場合のみ 表示されます（ポーリング間隔は最大12秒）。Herdr と tmux は状態変更を即座にプッシュするため、鮮度バッジは表示されません。
• —
  "端末で表示": このペインアクションは、アクティブなホスト端末で選択したペインにフォーカスします。zellij のフォーカス操作は指示を受け付けても表示状態を変更しないため、zellij では無効 になっています。

注。 モバイルインターフェースがホストターミナルのフォーカスを自動的に変更することはありません。明示的な「Show in terminal」操作のみが表示を更新します。ダッシュボードの移動やペインを開く操作は、アクティブなホストカーソルに影響しません（ADR 0031）。

tmux のヒント : 再起動後にウィンドウを復元する

Collie はマルチプレクサの状態を保存しません。tmux サーバーを再起動するとそのウィンドウは破棄され、ダッシュボードは空になります。

標準の tmux プラグインを使用して状態の復元を管理できます。プラグイン管理には tpm、セッションツリーの保存には tmux-resurrect、スナップショットの自動化には tmux-continuum を使用します。

これらのツールはウィンドウレイアウトと作業ディレクトリを復元します。会話のコンテキストを復元するには、Claudeに組み込まれたフラグ（claude --resumeまたはclaude --continue）を使用してください。

注。 実行中のエージェントプロセスは保持されません。復旧後はClaude Codeを手動で再起動してください。

zellij のヒント : 再起動後に復元するものはありません

zellijにはtmux-resurrectに相当する機能がありません。ターミナルのデタッチ後も存続しているセッションは(EXITED - attach to resurrect)として表示され、アタッチするとセッションコマンドが再実行されます。

注。 アタッチによって副作用が生じるため、Collieはセッションへのアタッチや復元を行いません。終了したセッションは到達不能として表示され、UIには空のセッションリストではなく切断バナーが表示されます。

再起動後は、セッションを手動で起動し（ヘッドレスシステムではzellij -s collie-zellijまたはzellij attach --create-background collie-zellij）、その中でエージェントを起動してください。以前のエージェントセッションへの再接続にはclaude --resumeまたはclaude --continueを使用します。

エージェントビーコン（任意、Linux）

ペインが一般的なシェルとして認識されてしまうtmuxやzellijにおいて、エージェントがCollieに対して自身を識別するためにbeaconを使用します。

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

Claude Codeの設定にあるフックがcollie beacon emitを実行し、ハーネス名、セッション、対象ペインを含むファイルを書き込みます。Herdrはこれをネイティブに追跡します。セットアップの詳細はCollieをマルチプレクサに向けるに記載されています。このセクションではその仕組みを説明します。

上記のパスはローカルチェックアウトの bin/collie を参照しています。バイナリインストールでは ~/.local/bin/collie を指し、その名前がリンクされていない場合は ~/.local/share/collie/current/bin/collie を指します (前述の通り)。status コマンドは書き込みを実行しません。

hooks uninstall claudeを実行すると、Collieによって追加されたエントリのみが削除されます。変更されるのはグローバルのClaude設定であり、プロジェクトレベルのファイルではありません。これはLinux専用です。生存確認で/procを検査するため、Collieは他のOSではビーコンを書き込みません。

起動するとClaudeは直ちに可視化されます。フックがSessionStartでトリガーされるため、入力を待機している開いたペインはシェルではなくアイドル状態のエージェントとして表示されます。

プロセスの終了と同時に可視性も失われます。Collieはチェックごとに送信元PIDを検証するため、エージェントが終了すると、ペインが不明な状態のまま残ることなく、直ちに標準のシェルとして報告されます。

Collieはこの処理においてビーコンファイルを削除しません。ファイルはディスク上に残り、collie doctorはbeaconsの下でそれを期限切れとして報告し、次回のフック実行時に上書きされます。

これにより、ダッシュボードでペインをbashではなくエージェント名でラベル付けできます。「要対応」によるブロック状態でのペインソートが可能になり、アラートに必要な状態が提供されます。ペインの履歴も、ジャーナルが使用するセッションキーの取得をビーコンに依存します。

注。 ビーコンは制御チャネルを提供しません。ビーコンは、Collieが何を表示（表示）し、何を追跡（問い合わせ）するかを決定するだけです。テキストの送信、キーストロークの挿入、ペイン名の変更、セッションの終了、アクセス制御のバイパスなどは行えません。脅威モデルと除外されたフィールドについてはADR 0024に記載されています。