Multiplexer

Collie는 설치당 하나의 multiplexer를 제어합니다: Herdr, tmux 또는 zellij. Herdr가 기본값입니다. 이 페이지에서는 세 가지 중 하나로 Collie를 지정하는 방법, 각 백엔드가 응답할 수 있는 항목, Collie가 창(pane) 내의 에이전트를 감지하는 데 사용하는 비콘을 다룹니다.

Collie를 multiplexer로 지정하기

COLLIE_MUX에 백엔드 이름을 지정하고 엔드포인트를 가리키도록 설정한 뒤, 재시작하고 beacon 훅을 설치하십시오.

1.0의 실험적 기능. tmux 및 zellij는 단일 호스트의 tmux 3.6b 및 zellij 0.44.2에서 테스트되었습니다. Herdr가 기본 백엔드이며 공식적으로 지원됩니다. 테스터 모집: AltanS/collie에 tmux: … 또는 zellij: …라는 제목으로 사용 중인 multiplexer, 버전, OS 및 확인된 현상을 포함하여 이슈를 등록해 주십시오.

명령줄에서 multiplexer를 지정합니다:

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만이 다른 머신의 세션을 휴대전화로 가져옵니다.

그런 다음 다시 시작하고 비콘 훅을 설치한 후 휴대전화에서 볼 수 있는 위치에 에이전트를 시작합니다:

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는 표준 경로 목록을 확인하며 PATH 환경 변수를 읽지 않습니다. 백그라운드 서비스 및 Herdr 액션은 로그인 셸과 이 환경 변수를 공유하지 않기 때문입니다.

참고. 소켓 경로를 짧게 유지하십시오. 대략 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는 세션을 임의로 선택하지 않고 오류와 함께 중단됩니다. 이름이 지정된 세션이 종료되면 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 구성 변경에 대한 동작 세부 정보:

• —
  global ~/.claude/settings.json 및 활성 CLAUDE_CONFIG_DIR을(를) 수정합니다. 프로젝트 수준의 .claude/settings.json 파일은 변경되지 않습니다.
• —
  10초 타임아웃이 지정된 # collie-beacon v1 태그의 5 훅을 주입합니다. 기존 훅은 유지됩니다. hooks uninstall claude 명령은 Collie 항목만 제거합니다.
• —
  실행 중인 Claude 프로세스는 설정을 다시 로드하지 않습니다. 변경 사항을 적용하려면 에이전트를 다시 시작하십시오.
• —
  Linux 전용. 에이전트 활성 상태 확인은 /proc에 의존합니다. 다른 운영 체제에서는 비콘을 내보내지 않습니다.
• —
  비콘은 멀티플렉서에 따라 다릅니다. 활성 백엔드의 창(pane) 및 세션 식별자를 기록합니다. COLLIE_MUX을(를) 전환하면 기존 비콘이 무효화됩니다. 이전 비콘은 정리될 때까지 디스크에 남아 있으며 collie doctor의 beacons 개수에서 확인할 수 있습니다.
• —
  COLLIE_STATE_DIR을(를) 사용하는 경우 에이전트의 셸 환경에서 이를 내보내십시오. collie beacon emit이(가) 이 변수를 직접 읽습니다. 그렇지 않으면 비콘이 기본 상태 디렉터리에 기록되어 브리지가 비콘을 찾지 못합니다.

collie doctor에는 누락된 후크나 이동된 체크아웃의 손상된 경로를 알려주는 beacon-hooks-claude 진단 검사가 포함되어 있습니다. 런타임에 대한 자세한 내용은 에이전트 비콘을(를) 참조하십시오.

Herdr 대비 변경 사항

아래 표는 주요 차이점을 요약합니다. 정확한 사양은 MUX_CONTRACT.md을(를) 참조하십시오.

활성 beacon이 없으면 tmux 및 zellij는 창을 기본 셸로 표시하며, 빈 내용을 반환하는 대신 창 기록을 사용할 수 없음으로 표시합니다.

모바일 환경에서 다르게 작동하는 두 가지

• —
  "Ns 전에 동기화됨": 이 표시기는 데이터 생성 시점을 나타내기 위해 대시보드 헤더에 표시됩니다. 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)

beacon은(는) 창이 일반 셸로만 표시되는 tmux 및 zellij 환경에서 에이전트가 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 설정의 훅이 collie beacon emit을(를) 실행하여 하네스 이름, 세션, 대상 창이 포함된 파일을 작성합니다. Herdr는 이를 기본적으로 추적합니다. 설정 세부사항은 Collie를 multiplexer로 지정하기에 있으며, 이 섹션에서는 작동 메커니즘을 설명합니다.

위 경로는 로컬 체크아웃의 bin/collie을(를) 참조합니다. 바이너리 설치는 ~/.local/bin/collie을(를) 가리키며, 해당 이름이 연결되지 않은 경우 ~/.local/share/collie/current/bin/collie을(를) 가리킵니다(위에서 설명한 바와 같이). status 명령은 쓰기 작업을 수행하지 않습니다.

hooks uninstall claude을(를) 실행하면 Collie가 추가한 항목만 제거됩니다. 프로젝트 수준 파일이 아닌 global Claude 구성을 수정합니다. 이는 Linux 전용입니다. 활성 상태 확인 시 /proc을(를) 검사하며, Collie는 다른 운영 체제에서 비콘을 작성하지 않습니다.

Claude는 시작 즉시 표시됩니다. 훅이 SessionStart에서 트리거되므로, 입력을 대기 중인 열린 창은 셸 대신 유휴 에이전트로 표시됩니다.

프로세스가 종료되면 표시가 중단됩니다. Collie는 확인할 때마다 송신 PID를 검증하므로, 에이전트가 종료되면 해당 창은 알 수 없는 상태로 남아 있지 않고 즉시 표준 셸로 보고됩니다.

Collie는 이를 위해 비콘 파일을 삭제하지 않습니다. 파일은 디스크에 남아 있고, collie doctor은(는) beacons 아래에 이를 만료됨(으)로 보고하며, 다음 훅 호출 시 덮어씁니다.

이를 통해 대시보드는 bash 대신 에이전트 이름으로 창의 라벨을 지정할 수 있습니다. 또한 "처리 필요" 창을 차단된 상태순으로 정렬 기능을 활성화하고, 알림에 필요한 상태를 제공합니다. 창 기록 역시 저널에서 사용하는 세션 키를 공급하기 위해 비콘에 의존합니다.

참고. 비콘은 제어 채널을 제공하지 않습니다. 비콘은 Collie가 무엇을 표시하고 조회하는지만 결정합니다. 텍스트를 보내거나, 키 입력을 주입하거나, 창 이름을 바꾸거나, 세션을 닫거나, 액세스 제어를 우회할 수 없습니다. 위협 모델 및 생략된 필드는 ADR 0024에 문서화되어 있습니다.