가이드

iPhone에서 Claude Code 실행하기

이 앱이 존재하는 이유를 그대로 따라가는 가이드입니다. 네 단계로 이루어집니다. 호스트에 연결하고, herdr를 설치하고, Claude Code를 시작한 뒤, 잠금 화면 알림을 탭해 이동한 패널에서 권한 프롬프트에 응답합니다. 여기에 나오는 문구와 명령은 모두 실제 출시 앱의 문자열과 Moshpit이 실행하는 실제 명령입니다.

1 호스트 연결
SSH 정보를 입력하고 호스트 지문을 한 번 확인한 뒤, 해당 연결의 멀티플렉서로 herdr를 선택합니다.
2 에이전트 시작
herdr 패널에서 claude를 입력하거나, Moshpit으로 새 git worktree를 만들고 그 안에서 Claude Code를 시작합니다.
3 휴대폰 내려놓기
Claude Code가 권한을 요청하면 잠금 화면에 알림이 표시되고, 탭하면 질문한 바로 그 패널로 이동합니다.

시작 전 준비 사항. 이미 SSH로 접속할 수 있는 서버, iOS 18 이상이 설치된 iPhone, 그리고 서버에 설치된 Claude Code가 필요합니다. Moshpit은 Claude Code를 대신 설치하거나 Anthropic과 직접 통신하지 않습니다. 셸을 연결해 줄 뿐이며, Claude Code는 그 안에서 실행되는 일반 프로그램입니다.

herdr는 선택 사항입니다. 에이전트 상태를 추측이 아닌 정확한 데이터로 다루기 위해 이 가이드에서는 herdr를 사용합니다. tmux 경로도 동일하게 동작하며 tmux 제어 모드와 푸시 및 실시간 현황에서 다룹니다.

1단계

호스트 연결하기

입력란 네 개와 지문 확인 한 번이면 됩니다. 이미 노트북에서 ssh로 접속할 수 있는 머신이라면 1분이면 끝납니다.

연결 추가

홈 화면 상단에서 +를 탭합니다. 입력 양식은 섹션별로 나뉘어 있습니다.

  • 연결(CONNECTION) — 이름, 호스트, 포트 (기본값 22), 사용자 이름. 이름과 호스트를 채우면 저장 버튼이 활성화됩니다.
  • 인증(AUTHENTICATION) — 암호 또는 SSH 키. 설정 → SSH 키에서 만든 키를 고르거나 양식에 PEM을 직접 붙여넣을 수 있습니다.
  • 고급(ADVANCED) — 멀티플렉서를 herdr로 설정합니다. 실행 파일이 특이한 위치에 있는 것이 아니라면 사용자 설정 경로는 비워 두세요. 직접 입력한 경로는 그대로 신뢰하며 기능 탐지를 건너뜁니다.

멀티플렉서는 전역이 아니라 연결마다 선택합니다. 서버마다 설치된 도구가 다르기 때문에 전역 기본값을 두면 “왜 이 서버만 안 붙지?” 같은 혼란만 생기기 때문입니다.

지문 한 번 확인하기

처음 연결할 때는 핸드셰이크를 잠시 멈추고 서버가 제시한 호스트 키를 보여 줍니다.

새 호스트

your-host:22에 처음 연결합니다.

키 지문:
SHA256:…

서버의 것과 같은지 확인하세요(예: `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`).

          [ 취소 ]   [ 신뢰 ]

Moshpit이 대신 지문을 검증해 줄 수는 없으므로 직접 대조할 명령을 함께 보여 줍니다. 저장된 키가 나중에 바뀌면 대화 상자가 ⚠️ 호스트 키 변경됨으로 바뀌고 두 지문을 나란히 표시하며, 기본 버튼은 연결 해제, 위험 동작 버튼은 새 키 신뢰로 표시됩니다.

지금 알아 둘 한계. 신뢰한 호스트 키를 목록으로 보거나 지우는 화면은 없습니다. 연결을 삭제해도 지문은 지워지지 않으며, 신뢰 정보는 기기별로 저장되고 백업에서 제외되므로 새 휴대폰에서는 모든 호스트를 다시 확인하게 됩니다. 정상적인 서버 키 교체 후에는 ⚠️ 대화 상자에서 변경을 수락하는 것이 앱 내 유일한 경로입니다.

또한 연결 양식에 직접 입력한 암호와 PEM은 Face ID 잠금 없이 저장됩니다. 키 추가에서 Face ID 필요를 켜고 만든 키만 읽을 때마다 인증을 요구합니다. 암호문구(passphrase)로 암호화된 개인 키는 지원하지 않습니다.

2단계

호스트에 herdr 설치하기

herdr는 CLI 코딩 에이전트를 위해 작성된 단일 Rust 바이너리입니다. 모든 패널의 프로토콜 필드로 agent_status를 직접 보고하므로, 호스트에 추가 스크립트를 깔지 않아도 Moshpit이 Claude Code의 대기 상태를 알 수 있습니다.

설치

# macOS / Linuxbrew
brew install herdr

# 그 외 환경
curl -fsSL https://herdr.dev/install.sh | sh

apt-get 명령은 안내하지 않습니다. herdr는 어느 Linux 배포판 저장소에도 등록되어 있지 않으며, 자체 패키징도 Windows만 지원합니다. Moshpit이 sudo apt-get install -y herdr 같은 명령을 지어내지 않는 이유도 여기에 있습니다. “패키지를 찾을 수 없음”으로 끝나는 명령은 앱 버그처럼 보이기 때문입니다.

설치 스크립트는 바이너리를 ~/.local/bin에 두고 의도적으로 셸 rc 파일은 건드리지 않습니다. Moshpit은 탐지와 실행 시 사용하는 PATH에 해당 디렉토리를 자동으로 포함하므로 호스트 설정을 따로 바꿀 필요가 없습니다.

설치되어 있지 않으면 그대로 알려 줍니다

herdr를 선택한 상태에서 herdr가 없는 호스트에 연결하면 실패 화면 대신 닫을 수 있는 배너가 나타납니다.

  • 배너: “이 호스트에 herdr가 없어 일반 셸 세션으로 연결했습니다.”와 함께 herdr 설치 동작이 제공됩니다.
  • 설치 도우미 시트에는 알맞은 명령과 함께 “Moshpit은 아무것도 몰래 설치하지 않습니다. 아래 명령을 셸에서 직접 실행하세요. sudo와 그 출력이 모두 보입니다.”라는 안내가 표시됩니다.
  • 터미널에서 실행을 탭하면 활성 셸에 명령을 붙여 넣어 sudo 프롬프트와 출력을 그대로 볼 수 있습니다. 옆에는 명령 복사와 다시 확인이 있습니다.
  • 세션 자체는 계속 동작합니다. 일반 셸이 열리며 몰래 tmux로 전환하지 않습니다. tmux와 herdr는 서로 무관한 세션을 관리하므로, 다른 쪽에 몰래 붙으면 전혀 다른 작업을 내 세션인 것처럼 보여 주는 꼴이 됩니다.

기준이 된 herdr 버전. 연동 설계는 herdr main / v0.8.0, 프로토콜 19를 기준으로 했고, 실기기 검증은 당시 brew install herdr로 설치된 0.7.3, 프로토콜 16에서 진행했습니다. 스냅샷 디코더는 누락된 필드가 있어도 전체 읽기를 실패시키지 않고 해당 항목만 단계적으로 축소하도록 작성되었습니다.

0.7.3에서 눈에 띄는 차이: 패널에서 실행 중인 명령이 보고되지 않으므로 상단 경로 표시의 세 번째 항목이 실행 명령 대신 패널 N으로 표시됩니다. 패널 선택 시트로 들어가는 유일한 입구이기 때문에 항목 자체는 유지됩니다.

이 가이드에서는 Mosh 대신 SSH를 사용하세요. Mosh는 렌더링된 화면 차분(diff)을 전송해 줄 프레이밍을 깨뜨리므로 herdr의 프레임 프로토콜을 실어 나를 수 없습니다 (tmux -CC를 실어 나를 수 없는 것과 같은 이유입니다). Mosh 위에서는 herdr가 자체 전체 화면 TUI를 띄우고 Moshpit은 렌더링만 담당해, 휴대폰 너비의 약 3분의 1을 herdr 사이드바가 차지합니다. 제어 시트는 별도의 SSH 사이드카를 통해 계속 동작합니다.

3단계

Claude Code 시작하기

두 가지 방법이 있습니다. 이미 열어 둔 패널에서 바로 실행하거나, Moshpit으로 격리된 git worktree를 만들어 그 안에서 시작하는 것입니다. 휴대폰에서는 두 번째 방법이 특히 유용합니다.

기존 패널에서 바로 실행

새로 배울 것 없음

  • herdr 패널에서 claude를 입력하면 끝입니다
  • herdr가 패널 화면 내용을 보고 에이전트를 감지합니다
  • 따로 설정하거나 외울 것이 없습니다

새 에이전트 작업

워크트리, 작업 공간, 에이전트를 한 번에

  • 홈 화면의 에이전트(AGENTS) 헤더에서 여는 시트 하나
  • 호스트에 새 git worktree를 만들고 그 안에서 Claude Code를 시작
  • 기존 작업 트리는 전혀 건드리지 않음
  • herdr 전용 — tmux에는 해당 기능이 없음

어느 쪽이든 herdr가 화면 내용에서 에이전트를 추론합니다. 추론 대신 직접 보고받으려면 호스트에서 herdr integration install claude를 한 번 실행하세요. 그러면 Claude Code가 자신의 상태를 직접 알립니다. 더 정확하지만 필수는 아니며, 이 가이드의 모든 내용은 없이도 동작합니다.

시트 항목별 설명

작업(TASK) 그룹 안내문: “호스트에 git worktree를 만들고 그 안에서 에이전트를 시작합니다. 지금 작업 중인 트리는 그대로입니다.”

  • 저장소(Repo) — 선택 메뉴입니다. Moshpit이 두 가지 방법으로 후보를 동시에 찾습니다. 열린 모든 패널의 작업 디렉토리를 git rev-parse --show-toplevel로 확인하고, 동시에 $HOME 아래를 수정 시각 순으로 스캔합니다. 찾는 동안에는 “저장소 찾는 중…”이, 아무것도 없으면 “찾지 못했습니다. 저장소 안에 있는 패널도 없고 홈 디렉토리에도 없습니다”가 표시됩니다. 맨 마지막 항목은 항상 기타…이며, 선택하면 저장소 경로 입력란이 나타납니다.
  • 브랜치(Branch) — 호스트로 보내기 전에 휴대폰에서 먼저 검증합니다. 빈 이름, 공백, 앞의 -나 /, 끝의 /, .., 끝의 .lock, 그리고 ~ ^ : ? * [ \ 문자는 모두 명확한 안내 문구(예: “브랜치 이름에 공백은 쓸 수 없습니다”)와 함께 차단됩니다. 잘못된 입력은 호스트까지 가지 않습니다.
  • 에이전트(Agent) — herdr server agent-manifests --json에서 읽어 옵니다. 기본 선택 우선순위는 claude, codex, 그다음 첫 번째 항목 순입니다. (알파벳순으로 정렬했을 때 실제 호스트에서 agy가 기본 선택되는 문제가 있어 알파벳순을 없앴습니다.)

첫 메시지(FIRST MESSAGE) 그룹 안내문: “선택 사항입니다. 에이전트가 실행되면 전달됩니다. 비워 두면 직접 입력할 수 있습니다.” 큰 저장소는 체크아웃에 수십 초가 걸릴 수 있으므로, 실행 중에는 시작 버튼이 시작 중…으로 바뀝니다.

‘시작’을 누르면 실제로 실행되는 명령

SSH로 세 개의 명령이 순서대로 실행됩니다. 숨기는 내용은 없으며, 사용자가 입력한 모든 레이블은 셸에 전달하기 전에 작은따옴표로 안전하게 감쌉니다.

herdr worktree create --cwd '~/code/payments-api' --branch 'fix-webhook-retry' \
     --label 'fix-webhook-retry' --focus --json
→ {"type":"worktree_created",
    "workspace":{"workspace_id":"w4"},
    "root_pane":{"pane_id":"w4:p1",
                 "cwd":"~/.herdr/worktrees/payments-api/fix-webhook-retry"}}

herdr pane run 'w4:p1' 'claude'          <- 명령을 입력하고 Return 실행

herdr agent send 'w4:p1' '<첫 메시지>'   <- 입력한 경우에만 2초 뒤 전송

새 git worktree, 새 작업 공간, 체크아웃 폴더에 들어간 포커스된 패널까지 한 번에 준비됩니다. 두 번째 단계에서 agent start 대신 의도적으로 pane run을 사용합니다. agent start --workspace는 워크트리 디렉토리를 상속하지 못해 엉뚱한 위치에서 열리기 때문입니다. pane run은 사용자가 직접 입력할 명령을 그대로 타이핑하므로 진행 과정을 눈으로 확인할 수 있습니다.

처음 보게 되는 화면

실기기 검증에서는 ~/.herdr/worktrees/…/fix-scroll-jump 경로의 작업 공간이 생성되었고, git worktree list로 브랜치 생성을 확인했으며, Claude Code가 실행되어 디렉토리 신뢰 확인 프롬프트에서 멈췄습니다. herdr는 해당 패널을 agent: claude / status: blocked로 표시했고, 홈 화면의 에이전트 섹션이 즉시 에이전트 1 · 대기 중으로 바뀌었습니다. 이 첫 번째 프롬프트가 바로 4단계에서 응답할 대상입니다.

작업 후 정리하기

홈 화면에서 작업 공간 행을 길게 누른 뒤 워크트리 제거를 선택합니다. 이 메뉴는 실제로 연결된 워크트리인 작업 공간에만 표시됩니다. 첫 번째 명령에는 절대 --force를 붙이지 않습니다.

  • “…”의 워크트리를 제거할까요? — “~/.herdr/worktrees 아래의 브랜치 체크아웃만 삭제합니다. payments-api 자체는 그대로입니다.”
  • 커밋하지 않은 변경 사항 때문에 herdr가 거부하는 경우에만 두 번째 대화 상자가 뜹니다. “…”에 커밋하지 않은 변경 사항이 있습니다 — “이 변경 사항은 다른 곳에 없습니다. 워크트리를 제거하면 모두 사라집니다.” 버튼은 그래도 삭제 / 유지이며, 명시적으로 ‘그래도 삭제’를 눌렀을 때만 --force가 추가됩니다.

이 단계의 한계를 솔직히 밝힙니다.

워크트리는 저장소 옆이 아니라 ~/.herdr/worktrees/<repo>/<branch>에 생성되며, 이 버전에서는 경로 지정 옵션이 없습니다(휴대폰에서 일일이 입력할 만한 설정이 아니기 때문입니다). 큰 저장소는 체크아웃에 수십 초가 걸립니다. 변경 사항이 남은(dirty) 저장소에서 git worktree add를 실행하는 경우는 문제없을 것으로 예상되나 별도 검증은 하지 않았습니다.

에이전트 플래그는 앱이 대신 고르지 않습니다. 매니페스트의 기본 claude 명령이 그대로 실행됩니다. --dangerously-skip-permissions 같은 옵션은 패널 안에서 직접 입력해야 합니다.

herdr는 자기 패널 안의 에이전트만 봅니다. 같은 머신의 Terminal.app에서 띄운 claude는 표시되지 않습니다. herdr는 프로세스 스캐너가 아니라 런타임이기 때문입니다. 실제로 유휴 상태인 herdr 패널 5개와 별도 터미널에서 바쁘게 도는 claude 1개가 있을 때, 에이전트 섹션이 정확히 “실행 중인 작업이 없습니다. 작업을 시작하면 별도 워크트리가 생깁니다”라고 표시해 사용자를 헷갈리게 한 적이 있습니다.

실기기 미검증 항목: 길게 누르기 컨텍스트 메뉴 자체는 자동화 도구로 SwiftUI 롱프레스를 구동할 수 없어, 메뉴 → 대화 상자 → 대화 상자 흐름은 컴파일과 단위 테스트로만 보증되며 실기기 녹화는 없습니다.

4단계

어디서든 권한 프롬프트에 응답하기

Claude Code가 멈춰 서서 명령을 실행해도 되는지 묻습니다. 이 사이트에서 호박색(Amber)은 오직 “에이전트가 사람을 기다린다”는 뜻으로만 쓰이며, 바로 이 순간 잠긴 휴대폰 화면에 알림으로 나타납니다.

iPhone 잠금 화면: m1-pro에서 claude가 Bash 사용 권한을 요청하는 시간 민감성 Moshpit 알림

잠긴 휴대폰에 도착한 질문 제목은 에이전트 이름, 본문은 무엇을 어디서 묻는지 보여 줍니다 — Claude needs your permission to use Bash — m1-pro · pit. 한 호스트에서 여러 에이전트가 기다리면 카드 하나로 묶입니다: claude +2.

한 번의 탭 질문한 바로 그 패널로 이동합니다. 진짜 터미널에서 프롬프트를 직접 읽고, 책상에서 누르던 그 키 그대로 응답합니다.

‘허용’ 버튼을 일부러 뺐습니다 예전에 잠금 화면에 넣었던 버튼은 내용을 보지도 않고 패널에 키 입력을 맹목적으로 보냈습니다. 화면을 직접 확인할 수 있다는 점이 이 앱의 핵심 가치인데, 읽지도 않고 승인하는 것은 잘못된 타협이어서 버튼을 없앴습니다.

앱이 꺼져 있어도 휴대폰에 알림이 도착하는 방식

일시 중단된 iPhone이 할 수 없는 일을 호스트가 대신합니다. 패널에 상태를 기록하는 바로 그 훅이 working을 제외한 attention과 done 이벤트를 작은 전송 스크립트(~/.moshpit/moshpit-push.sh)로 넘깁니다. 스크립트는 내 휴대폰만 가진 키로 알림을 암호화한 뒤 암호문을 Moshpit 푸시 릴레이와 Apple을 거쳐 보냅니다. 어느 쪽도 단 1바이트도 읽을 수 없으며, 에이전트 이름·명령·질문 내용은 잠금 화면을 포함해 휴대폰의 알림 확장(Notification Extension) 안에서 복호화됩니다. 페어링은 호스트에서 알림을 처음 켤 때 자동으로 진행되며, 사용자가 직접 동의해야 하는 단계는 최초 훅 설치 한 번뿐입니다.

적용 범위를 분명히 밝힙니다. 전송 스크립트는 에이전트 훅을 타고 동작하며, 훅은 tmux 패널에 상태를 기록합니다. 따라서 앱이 닫힌 상태에서도 푸시를 받으려면 훅이 설치된 tmux 아래에서 에이전트를 실행해야 합니다. 순수 herdr 패널에서는 Moshpit이 실행 중인 동안 herdr의 agent_status가 Dynamic Island와 알림을 구동하며, 앱이 꺼지면 중단됩니다. 앱이 닫혀 있을 때 깨워 주는 기능이 핵심이라면 현재로서는 tmux 패널에서 Claude Code를 실행하세요.

조용함을 지키는 네 가지 규칙

모든 일에 알림을 울리는 것은 아무 알림도 안 주는 것과 같습니다. 방해할 만한 이유가 충분할 때만 울립니다.

규칙의미
30초 대기 유예 유예 시간 안에 책상에서 답한 질문은 휴대폰으로 알리지 않습니다.
호스트당 카드 하나 기다리는 에이전트가 모두 하나의 요약(“claude +2”)으로 묶입니다. 기다리는 에이전트 없음 → 있음으로 바뀌는 순간에만 소리가 울리고 집중 모드를 통과할 수 있으며, 이후 변동은 카드만 조용히 갱신됩니다.
완료 알림음은 3분 이상만 3분 이상 걸린 턴이 끝났을 때만 소리를 냅니다. 짧은 작업은 화면을 깨우지 않고 알림 목록에만 조용히 쌓입니다.
세워 둔 에이전트는 침묵 프롬프트에 일부러 세워 둔 유휴 에이전트는 아무 알림도 울리지 않으며, 하루 이상 묵은 “대기 중” 상태는 자동으로 완료 처리됩니다.

작은 디테일도 챙겼습니다. 앱에서 프롬프트를 확인하면 읽음 처리되며, 재연결하거나 앱을 다시 열어도 이미 알려 준 질문으로 알림을 다시 울리지 않습니다.

알림을 제어하는 네 가지 스위치

설정 → 알림(NOTIFICATIONS). 네 항목 모두 기본으로 켜져 있습니다.

  • 알림 — “에이전트가 기다리면 알림”
  • 실시간 현황 — “Dynamic Island에 에이전트 세션 상태 표시”
  • 알림음 — “에이전트가 기다릴 때 소리 재생”
  • 잠금 화면에 자세히 표시 — “에이전트가 실행 중인 것, 묻는 것, 처리한 프롬프트를 표시합니다. 끄면 내용을 숨깁니다”. 끄더라도 작업 중 / 대기 중 / 완료 상태는 보이지만 Bash: npm install 같은 구체적인 줄은 가려집니다.

알림과 실시간 현황을 모두 끄면 감시 자체가 중단됩니다. 스위치 아래의 이 호스트 설정 행에서는 연결된 호스트에 어떤 에이전트 훅이 깔려 있는지, 푸시 전송 스크립트가 있는지, 이 휴대폰과의 페어링 상태를 확인할 수 있습니다. 설정 자체는 연결 시 자동으로 안내됩니다.

호박색 점과 느낌표를 표시하는 Dynamic Island: 에이전트가 대기 중

잠금 해제 상태 · 대기 중 대기 중인 에이전트가 하나면 호박색 느낌표를, 여러 개면 개수를 표시합니다. 기본 바에는 에이전트 하나만 표시되며 길게 누르면 확장 보기에서 나머지도 함께 볼 수 있습니다.

청록색 점과 실시간 타이머를 표시하는 Dynamic Island: 에이전트 작업 중

잠금 해제 상태 · 작업 중 Claude Code가 작업하는 동안 청록색 표시와 실시간 타이머가 돌아갑니다. 생각하는 에이전트와 멈춰 기다리는 에이전트가 한눈에 구분됩니다.

솔직한 한계

앱을 백그라운드로 보내면 생기는 일

위 기능들에 의존하기 전에 꼭 읽어 두어야 할 절입니다. 종단간 암호화 푸시가 대부분의 공백을 메우지만, 메우지 못하는 부분도 여기에 그대로 적었습니다.

iOS가 연결을 일시 중단하면 실시간 화면도 멈춥니다

iOS가 앱을 일시 중단하면 2초 주기 갱신과 SSH 폴링도 함께 멈춥니다. 이 공백을 건너오는 것이 4단계의 푸시 경로입니다. 호스트의 훅이 attention과 done을 감지해 암호화 알림을 직접 보내므로, 앱이 닫혀 있거나 휴대폰이 잠겨 있어도 알림이 도착합니다.

반면 공백을 건너오지 못하는 것은 실시간 현황(Live Activity)입니다. 앱이 마지막으로 확인한 상태를 그릴 뿐, 앱이 중단된 동안에는 새 데이터를 공급받지 못합니다. 실기기 측정에서도 Moshpit을 백그라운드로 보낸 상태에서 패널이 ‘대기 중’에서 ‘작업 중’으로 바뀌었을 때, 앱을 다시 앞으로 불러와 한 번 폴링하기 전까지는 Dynamic Island가 그대로 유지되었습니다.

그래서 거짓말 대신 “일시 정지됨”을 표시합니다

Moshpit                      2개 작업 중 · 1개 대기 중
●  claude                   대기 중 · 2분
   mac-studio · ~ · Tab 1
   Bash: npm install

… 앱이 2분 동안 일시 중단됨 …

Moshpit            일시 정지됨 — Moshpit을 열어 새로 고치세요

실시간 현황은 120초(갱신 2회 누락)의 유효 시간(staleness horizon)을 가지며, 시간이 지나면 멈춘 “작업 중”을 거짓으로 띄워 두는 대신 “일시 정지됨” 안내로 전환합니다. 홈 화면 위젯은 180초 기준이며 오래되면 모든 상태 점을 회색으로 흐리게 표시합니다. 4단계의 푸시 전송기가 설치되어 있다면 이와 무관하게 푸시 알림은 계속 도착합니다.

포그라운드에서도 외부 변경 사항에는 약간의 지연이 있습니다

  • herdr 제어 폴링은 변화가 있을 때 2초마다 실행되고, 동일한 응답이 세 번 연속 나오면 8초로 느려집니다. 변화가 감지되거나 당겨서 새로 고치면 즉시 2초로 돌아옵니다.
  • 앱 안에서 수행한 작업은 즉시 새로 고쳐집니다. 모든 변경 직후 다시 읽어 오기 때문입니다. 반면 바깥(노트북, 다른 클라이언트, 에이전트 자체 상태 변화)에서 일어난 일은 최대 8초 뒤에 반영될 수 있습니다.
  • 그래서 경과 시간을 초 단위가 아니라 분 단위(지금, 2m, 1h 12m)로만 표시합니다. 원본 데이터가 최대 8초 간격인데 초 단위까지 찍으면 실제로는 없는 정밀도를 과장하는 셈이기 때문입니다.
  • herdr 소켓 API에는 이벤트 구독 기능이 있지만 CLI에 subscribe 명령이 노출되어 있지 않고, 휴대폰이 호스트의 Unix 소켓을 직접 열 수도 없습니다. 현재로서는 폴링이 유일한 수단입니다.

같은 패널에 Moshpit 클라이언트 둘이 붙으면 서로 충돌합니다

herdr의 직접 연결(direct attach)은 패널당 단독 점유 방식입니다. 재연결 시 항상 직전의 오래된 채널과 충돌하기 때문에 Moshpit은 --takeover로 붙을 수밖에 없습니다. 따라서 같은 패널에 휴대폰 두 대가 동시에 붙으면 약 2초마다 서로 소유권을 뺏고 빼앗습니다. 이는 단독 점유 방식의 구조적 특성이므로 클라이언트에서 해결할 수 없습니다.

Moshpit의 대응: 30초 안에 예기치 않은 종료가 세 번 발생하면 30초간 일시 멈추고 “다른 클라이언트가 이 패널을 쓰고 있습니다. 잠시 후 재시도” 안내를 띄우며, 프레임이 다시 그려지면 자동으로 사라집니다. 노트북에서 herdr 자체 TUI를 실행하는 것은 attach 슬롯을 점유하지 않으므로 노트북 + 휴대폰 조합은 안전할 것으로 보이나, 이 조합은 아직 직접 검증하지 않았습니다.

자주 묻는 질문

이 가이드에서 자주 나오는 질문들

꼭 herdr를 써야 하나요?

아니요. tmux에서는 설정 → 알림 → 에이전트 훅 설치로 명령 한 번만 실행하면 Claude Code의 UserPromptSubmit, PreToolUse, Notification, Stop 훅이 등록되어 tmux 패널에 상태를 기록합니다. 먼저 ~/.claude/settings.json을 백업하고, 항상 exit 0으로 종료해 에이전트를 막지 않으며, 두 번 실행해도 중복을 제거합니다. 훅이 없으면 Moshpit은 패널 출력과 터미널 벨에 의존하는 추측 모드로 동작하며, 화면에도 추측임을 명시합니다. 단, 홈 화면의 에이전트 전용 작업 생성은 herdr 전용입니다.

Moshpit이 닫혀 있어도 깨워 줄 수 있나요?

네, 그것이 푸시 경로의 목적입니다. 호스트의 훅이 내 휴대폰만 가진 키로 알림을 암호화해 Moshpit 릴레이로 보내고, 휴대폰이 잠겨 있고 앱이 닫혀 있어도 알림 확장이 잠금 화면에서 복호화해 띄웁니다. 4단계의 범위 안내를 기억하세요. 전송 스크립트는 tmux 패널에 기록하는 에이전트 훅을 타고 동작하므로, 앱이 꺼진 상태의 알림이 중요하다면 tmux 아래에서 에이전트를 실행하세요. 조용함 규칙(30초 유예, 호스트당 카드 하나, 완료음은 3분 이상만, 유휴 에이전트 침묵)은 푸시 및 실시간 현황에 자세히 나와 있습니다.

Mosh는 어떤가요?

Wi-Fi에서 5G로 전환돼도 끊기지 않는 셸을 원한다면 Mosh가 제격이지만, herdr의 프레임 프로토콜이나 tmux -CC는 실어 나를 수 없습니다. Mosh 위에서는 herdr가 터미널 안에서 자체 TUI를 실행해 휴대폰 너비의 약 3분의 1을 사이드바가 차지합니다. 제어 시트는 별도 SSH 사이드카로 계속 동작합니다. 이 가이드에는 SSH를 권장합니다. 자세한 내용은 Mosh 문서를 참고하세요.

Claude Code가 실행 중인데 에이전트 섹션이 비어 있습니다.

대부분 herdr 패널 안에서 실행되지 않았기 때문입니다. herdr는 자기 패널을 지켜보며 에이전트를 식별하므로, Terminal.app이나 별도 SSH 세션에서 띄운 claude는 보이지 않습니다. 새 에이전트 작업으로 시작하거나 herdr 패널 안에서 실행하세요. herdr 0.7.3에서는 에이전트 이름이 보고되지 않아 유휴 에이전트 행이 아예 생성되지 않는 현상도 있습니다.

Moshpit이 내 코드나 프롬프트 등을 읽나요?

Moshpit은 계정도 분석 도구도 없으며, 터미널 트래픽은 사용자가 추가한 서버로만 갑니다. Moshpit이 운영하는 유일한 서버인 푸시 릴레이는 열 수 없는 암호문만 전달합니다. 알림은 호스트에서 내 휴대폰만 가진 키로 암호화됩니다. 패널 밖으로 나가는 유일한 정보는 훅의 짧은 제목(에이전트가 실행하거나 묻는 내용, 최대 80자)이며, 이 역시 암호화되어 전달되고 내 잠금 화면에서만 표시됩니다.

다음에는 무엇을 읽으면 좋을까요?

연결 양식과 호스트 키 동작은 호스트 및 키, herdr 용어와 키 바인딩은 herdr, 알림과 실시간 현황 세부 동작은 푸시 및 실시간 현황을 참고하세요. 연결이 안 되거나 동작이 이상할 때는 문제 해결부터 확인하세요.

이어서 보기: 어디서나 내 머신에 연결하기 · 가이드 목록으로