多路复用器

每个 Collie 安装实例驱动一个多路复用器：Herdr、tmux 或 zellij。Herdr 是默认选项。本页介绍如何将 Collie 指向这三者之一、各后端能响应的内容，以及 Collie 用于检测窗格中 agent 的 beacon。

将 Collie 指向多路复用器

在 COLLIE_MUX 中指定后端名称，将其指向端点，重启，然后安装 beacon hook。

在 1.0 中处于实验阶段。 tmux 和 zellij 已在 tmux 3.6b 与 zellij 0.44.2 的单台主机上完成测试。Herdr 是默认且主要支持的后端。征集测试者： 请在 AltanS/collie 上提交 issue，标题格式为 tmux: … 或 zellij: …，并附上你的多路复用器、版本、操作系统以及观察到的现象。

在命令行中指定多路复用器：

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 机器并在单个 Herdr 客户端中显示多台服务器，但 Collie 不会读取其中任何一台，因此在 Herdr 中保存的机器不是 pack 成员；只有 Collie pack 才能将其他机器的会话接入手机。

然后重启，安装 beacon 钩子，并在手机可见的位置启动 agent：

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 会安装 Collie 的 beacon hook，tmux 和 zellij 都需要它们。它们将窗格暴露为通用 shell，因此如果没有 hook，每个窗格都会显示为 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 会检查一系列标准路径，不会读取 PATH，后台服务和 Herdr 动作不会与登录 shell 共享该变量。

注意。 保持套接字路径简短。长度超过约 100 个字符的 Unix 域套接字会连接失败，tmux 会返回 error connecting to … (File name too long)。请使用 /run/user/<uid>/ 或 /tmp，而不是较深的目录路径。

在低于 3.7 且 window-size 设置为 manual 的 tmux 版本上，创建窗口会导致服务器崩溃。Collie 在此状态下会阻止窗口创建并提示运行 tmux set -g window-size latest；环境要求 列出了测试过的版本。

zellij 说明

如果你的发行版缺少 zellij 软件包，请从 zellij 的 GitHub release 页面 下载二进制文件并放入 PATH 中。

端点留空时，默认使用单个运行中的会话。如果不存在会话或存在多个会话，Collie 会停止运行并报错，而不会随意选择一个。如果具名会话退出，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 窗格应识别为 agent 而不是 bash。如果窗格仍显示为标准 shell，请检查下方的 beacon hook 安装情况。

Collie 将 hook 写入 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 将窗格暴露为通用 shell，agent 必须自行声明身份。这需要在 Claude Code 的配置中安装 Collie 的 beacon hook。

输出引用了此仓库中的 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 hook。现有的 hook 会被保留。hooks uninstall claude 仅删除 Collie 条目。
• —
  正在运行的 Claude 进程不会重新加载配置。 重启 agent 以应用更改。
• —
  仅限 Linux。 agent 存活检查依赖于 /proc。其他操作系统不会发出 beacon。
• —
  Beacon 区分多路复用器。 它们会记录当前活跃后端的 pane 和 session 标识符。切换 COLLIE_MUX 会使现有的 beacon 失效。旧的 beacon 会一直保留在磁盘上直到被清除，并显示在 collie doctor 的 beacons 计数中。
• —
  如果使用 COLLIE_STATE_DIR，请在 agent 的 shell 环境中导出它。collie beacon emit 会直接读取此变量；否则，beacon 将写入默认状态目录，导致 bridge 无法找到它们。

collie doctor 包含一项 beacon-hooks-claude 诊断检查，可指出缺失的 hook 或移动检出后的损坏路径。有关运行时详情，请参阅 Agent beacon。

与 Herdr 相比有哪些变化

下表总结了主要差异。具体规范请参考 MUX_CONTRACT.md。

若没有活跃的 beacon，tmux 和 zellij 会将 pane 显示为原始 shell，且 pane 历史记录会被标记为不可用，而不是返回空内容。

手机端体验不同的两点

• —
  "synced Ns ago"： 此指示器显示在仪表盘顶部，用于展示数据时效。它仅在后端依赖计划轮询时显示，例如 zellij（轮询间隔最长 12 秒）。Herdr 和 tmux 会立即推送状态变更，因此会省略新鲜度徽标。
• —
  "Show in terminal"： 此 pane 操作会在活跃的宿主机终端中聚焦选中的 pane。该操作在 在 zellij 上已禁用，因为 zellij 的 focus 命令虽接受指令但不会改变视图状态。

注意。 移动端界面绝不会自动更改主机终端的焦点。只有明确执行“Show in terminal”操作时才会更新显示。浏览仪表板或打开窗格不会影响活动的主机光标 (ADR 0031)。

tmux 提示：重启后恢复窗口

Collie 不存储多路复用器的状态。重启 tmux 服务器会销毁其窗口，导致仪表板变空。

您可以使用标准 tmux 插件管理状态恢复：使用 tpm 进行插件管理，使用 tmux-resurrect 保存会话树，使用 tmux-continuum 进行自动快照。

这些工具用于恢复 窗口布局 和工作目录。如需恢复对话上下文，请使用 Claude 的内置标志：claude --resume 或 claude --continue。

注意。 运行中的 agent 进程不会被保留。恢复后请手动重启 Claude Code。

zellij 提示：重启后无需恢复任何内容

Zellij 未提供与 tmux-resurrect 等效的功能。终端分离后保留的会话会显示为 (EXITED - attach to resurrect)，且附加操作会触发会话命令的重新执行。

注意。 由于附加操作会产生副作用，Collie 不会附加到会话或恢复会话。已退出的会话显示为 不可达，UI 会显示断开连接横幅，而不是空白的会话列表。

重启后，手动启动会话（无头系统使用 zellij -s collie-zellij 或 zellij attach --create-background collie-zellij），并在其中启动 agent。使用 claude --resume 或 claude --continue 重新连接到先前的 agent 会话。

Agent 信标（可选，Linux）

在 tmux 和 zellij 中，窗格通常只显示为普通 shell，agent 通过 beacon 向 Collie 标识自身。

$ 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 设置中的 hook 会运行 collie beacon emit，该命令会写入一个包含 harness 名称、会话和目标窗格的文件。Herdr 原生跟踪此内容。配置详情请参阅 将 Collie 指向多路复用器；本节仅解释其机制。

上面的路径引用了本地检出中的 bin/collie。二进制安装指向 ~/.local/bin/collie，或者在该名称未链接时指向 ~/.local/share/collie/current/bin/collie，如上所述。status 命令不执行任何写入操作。

运行 hooks uninstall claude 仅会移除 Collie 添加的条目。它会修改你的 全局 Claude 配置，而不会修改项目级文件。此功能仅限 Linux：活跃度检查会检查 /proc，且 Collie 不会在其他操作系统上写入 beacon。

Claude 在启动时立即变为可见。由于 hook 会在 SessionStart 时触发，等待输入的打开窗格会显示为空闲 agent 而非 shell。

进程退出时可见性即终止。Collie 在每次检查时都会验证发送方 PID，因此一旦 agent 终止，该窗格会立即报告为标准 shell，而不会停留在未知状态。

Collie 不需要删除 beacon 文件来实现此操作：文件仍保留在磁盘上，collie doctor 会在 beacons 下将其报告为 已过期，下一次 hook 调用会覆盖该文件。

这允许仪表盘按 agent 名称而非 bash 标记窗格。它支持 “需要你”按阻塞状态对窗格排序，并提供告警所需的状态。窗格历史记录也依赖信标来提供日志使用的会话密钥。

注意。 Beacon 不提供控制通道。Beacon 仅决定 Collie 显示 和 查询 的内容。它无法发送文本、注入按键、重命名窗格、关闭会话或绕过访问控制。威胁模型和省略的字段记录在 ADR 0024 中。