// guide

VibeShell Hook 활용방법

다중 프로젝트 관리, 토픽 설정, 대화형 관리 도구 사용법을 안내합니다.

대화형 관리 도구

설치 스크립트를 인자 없이 실행하면 대화형 메뉴가 표시됩니다.

관리 도구 실행

~/.vibeshell/install.sh

=== VibeShell Push Hook 관리 ===

현재 설정:
  서버 URL: https://push.vibeshell.app
  활성화:   예
  전역 토픽:
    - vbs_abc123

  프로젝트 (2개):
    [ON]  my-project
        경로: /Users/dev/my-project
    [OFF] old-project
        경로: /Users/dev/old-project

메뉴:
  [1] 프로젝트 추가
  [2] 프로젝트 삭제
  [3] 프로젝트 활성화/비활성화
  [4] 토픽 ID 관리
  [5] 서버 URL 변경
  [6] 훅 스크립트 업데이트
  [0] 종료

다중 프로젝트 관리

여러 프로젝트를 등록하면 경로 기반으로 자동 매칭됩니다. 등록되지 않은 경로에서는 알림이 전송되지 않습니다.

{
  "projects": {
    "vibeshell": {
      "paths": ["/Users/dev/vibe-shell"],
      "enabled": true
    },
    "wvsh": {
      "paths": ["/Users/dev/wvsh"],
      "enabled": true
    },
    "agent-flow": {
      "paths": [
        "/Users/dev/agent-flow",
        "/home/server/agent-flow"
      ],
      "enabled": false
    }
  }
}

•paths — 한 프로젝트에 여러 경로를 등록할 수 있습니다 (로컬 + 서버)

•enabled — 프로젝트별로 알림을 켜고 끌 수 있습니다

•경로 매칭 — 현재 작업 디렉토리가 등록된 경로로 시작하면 매칭됩니다 (하위 디렉토리 포함)

토픽 ID 관리

토픽 ID는 VibeShell 앱에서 디바이스를 식별하는 키입니다. 전역 토픽과 프로젝트별 토픽을 조합하여 사용할 수 있습니다.

전역 토픽

모든 프로젝트에 기본 적용되는 토픽입니다. 여러 디바이스에 동시에 알림을 보내려면 토픽을 여러 개 등록하세요.

"topic_ids": ["vbs_phone", "vbs_tablet"]

프로젝트별 토픽 오버라이드

특정 프로젝트의 알림을 다른 디바이스로 보내고 싶을 때 프로젝트 레벨에서 토픽을 오버라이드할 수 있습니다.

"important-project": {
  "paths": ["/Users/dev/important"],
  "enabled": true,
  "topic_ids": ["vbs_urgent_phone"]
}

Claude Code 훅 구조

설치 스크립트가 자동으로 ~/.claude/settings.json에 Stop hook을 등록합니다.

// ~/.claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.vibeshell/hook.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

hook.sh는 jq 또는 python3를 사용하여 설정을 파싱합니다. 타임아웃은 30초이며, 실패해도 Claude Code 작업에 영향을 주지 않습니다.

활용 시나리오

💻

원격 서버 작업 알림

서버에서 Claude Code로 긴 작업을 실행하고, 완료되면 모바일로 알림을 받아 바로 확인할 수 있습니다.

👥

팀 프로젝트 모니터링

같은 토픽을 팀원들이 공유하면 누가 어떤 프로젝트에서 작업을 완료했는지 실시간으로 알 수 있습니다.

🔀

다중 프로젝트 관리

여러 프로젝트를 동시에 진행할 때, 각 프로젝트의 완료 알림을 별도 토픽으로 분류하여 관리할 수 있습니다.

🌙

야간 배치 작업

긴 마이그레이션이나 리팩토링 작업을 실행해두고 다른 일을 하다가 알림으로 완료를 확인할 수 있습니다.

빠른 명령어

현재 설정 보기~/.vibeshell/install.sh show

알림 비활성화jq '.enabled = false' ~/.vibeshell/push-config.json | sponge ~/.vibeshell/push-config.json

알림 활성화jq '.enabled = true' ~/.vibeshell/push-config.json | sponge ~/.vibeshell/push-config.json

훅 수동 테스트cd /your/project && ~/.vibeshell/hook.sh

VibeShell Hook 소개 VibeShell Gateway 소개 고객지원