Wendov1.0 · iOS & Android
한국어

가이드

폰에서 받는 Claude Code 알림과 승인

· 5분 읽기

Claude Code에는 훅이 있습니다. 특정 시점에 당신이 정한 명령을 실행하는 지점입니다. 권한을 요청하거나 작업을 끝낼 때 알림을 만들기에 충분하고, 폰에서 답하는 것까지 가능합니다. 내부에서 어떻게 돌아가는지, Wendo가 이를 어떻게 쓰는지 설명합니다.

Claude Code 훅이란

훅은 무슨 일이 생길 때 Claude Code가 실행하는 명령입니다. 세션이 시작될 때, 프롬프트를 보낼 때, 권한이 필요할 때, 답변을 마쳤을 때가 그런 시점입니다. ~/.claude/settings.json에 이벤트마다 키 하나를 두고, 각각 명령을 지정합니다.

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "~/.wendo/wendo-hook.sh" }] }
    ]
  }
}

Claude Code는 그 명령을 실행하면서 표준 입력으로 이벤트 데이터가 담긴 JSON 문서를 넘깁니다. 이벤트 이름, 작업 디렉터리, 세션 ID, 경우에 따라 사용하려는 도구 같은 것들입니다. 명령은 이 데이터로 무엇이든 할 수 있습니다. 일부 이벤트에서는 표준 출력에 응답을 쓸 수도 있고, Claude Code는 그렇게 결정을 알게 됩니다.

Wendo의 훅이 등록하는 이벤트

설치 프로그램은 같은 스크립트를 이벤트 여섯 개에 추가합니다.

  • PermissionRequest: Claude Code가 막 권한을 요청하려는 때.
  • Notification: 주의가 필요한 Claude Code의 알림.
  • Stop: 답변을 마쳤을 때.
  • UserPromptSubmit: 프롬프트를 보냈으니 작업 중이라는 뜻.
  • SessionStart와 SessionEnd: 세션이 시작되거나 끝날 때.

각 이벤트는 컴퓨터의 ~/.wendo/events.jsonl에 한 줄로 저장됩니다. 앱은 당신의 키로 SSH를 통해 이 파일을 읽으므로 중간 서버도 계정도 없습니다. 받은 편지함에 보이는 내용은 여기서 나옵니다.

설치는 명령 하나입니다.

curl -fsSL https://wendo.lirafy.dev/install.sh | sh

settings.json을 건드리기 전에 settings.json.bak-wendo로 사본을 저장하며, 여러 번 실행해도 항목이 중복되지 않습니다. 이미 있는 훅은 그대로 둡니다. 옵션과 수동 설정은 알림과 승인 문서에 있고, 환경 전체를 구성하는 더 넓은 안내는 폰에서 Claude Code 사용하기에 있습니다.

승인이 동작하는 방식

PermissionRequest는 훅이 머물며 기다리는 유일한 이벤트입니다. Claude Code가 권한을 요청하면 스크립트는 그 요청을 보류 상태로 기록하고, 앱의 받은 편지함에는 승인·거부 버튼이 달린 행이 나타납니다. 하나를 탭하면 앱이 컴퓨터의 파일에 답을 남기고, 훅이 그것을 집어 Claude Code에 결정을 넘깁니다.

대기 시간은 90초입니다. 그때까지 답하지 않으면 훅은 아무것도 출력하지 않고, Claude Code는 Wendo가 없는 것처럼 터미널에서 평소의 프롬프트를 보여 줍니다. 이 점이 중요합니다. 폰이 꺼지거나 신호가 끊겨도 막히는 것은 없고, 원래 방식으로 돌아갈 뿐입니다.

폰보다 먼저 터미널에서 답하면 그것도 로컬에서 처리됨으로 기록됩니다.

몇 가지 환경 변수로 조절하며, 훅 명령 앞에 지정합니다.

  • WENDO_APPROVAL_TIMEOUT: 기다릴 초 단위 시간. settings.json의 훅 timeout(설치된 설정에서는 120)이 이보다 커야 합니다.
  • WENDO_BLOCKING=0: 알림만 보내고 답을 기다리지 않습니다.
  • WENDO_HOST: 앱이 컴퓨터를 부르는 이름. hostname -s와 다를 때 씁니다.

Claude의 질문(AskUserQuestion)과 계획 승인(ExitPlanMode)은 대기하지 않습니다. 예·아니오가 아니라 선택을 요구하므로 채팅 보기에서 답합니다.

앱을 닫았을 때의 알림: ntfy

Wendo가 열려 있는 동안 앱은 몇 초마다 받은 편지함을 읽습니다. 앱을 닫으면 누군가 알림을 폰으로 밀어 줘야 하고, 그 역할을 하는 것이 ntfy입니다. HTTP 요청 하나로 발행하는 간단한 푸시 알림 서비스입니다.

  1. settings.json의 훅 명령 앞에 NTFY_TOPIC을 붙입니다.
NTFY_TOPIC=a-long-random-topic ~/.wendo/wendo-hook.sh
  1. 폰에 ntfy 앱을 설치하고 같은 토픽을 구독합니다.
  2. Wendo에도 설정 › 에이전트 › 알림에서 같은 토픽을 입력합니다.

아무도 짐작하지 못할 토픽을 만들려면 다음을 쓰세요.

openssl rand -hex 16

토픽은 비밀번호와 같습니다. 공개 ntfy 서버에서는 토픽 이름을 아는 사람이면 누구나 거기에 발행된 내용을 읽고 자기 메시지를 발행할 수 있으므로 claude-john 같은 이름은 쓰지 마세요. 알림에는 프로젝트와 메시지 또는 명령의 일부가 들어 있어 판단하기엔 충분하지만, 낯선 사람이 읽기를 바라는 내용은 아닙니다.

공개 서버에 의존하고 싶지 않다면 NTFY_URL로 훅이 직접 운영하는 ntfy 서버를 가리키게 할 수 있습니다. 기본값은 https://ntfy.sh입니다. 알림을 탭하면 에이전트가 실행 중인 tmux, zellij, herdr 패널이 열립니다. 에이전트를 그 안에서 실행하고 있어야 합니다(tmux 문서 참고).

Android에서는 최소 15분마다 백그라운드 확인도 합니다. ntfy로 가는 것은 권한, 알림, 작업 완료 알림뿐입니다. 훅은 세션 시작, 세션 종료, 모든 프롬프트를 푸시하지 않습니다.

제한 사항

  • 지금은 Claude Code만 지원합니다. 다른 에이전트에는 훅이 등록되지 않습니다.
  • 컴퓨터에 jq가 필요합니다. curl은 ntfy에만 필요합니다.
  • 멀티플렉서가 없으면 앱은 Claude가 어느 패널에 있는지 몰라서 곧장 데려갈 수 없습니다.
  • 무료 플랜에는 받은 편지함에서 쓸 수 있는 체험 승인 5회가 포함됩니다. Pro에는 제한이 없습니다.
  • Wendo는 아직 스토어에 없습니다. App Store와 Google Play에 곧 출시됩니다.