// vibeshell-hook

VibeShell Hook

AI 코딩 도구 작업이 완료되면 VibeShell 앱으로 푸시 알림을 보내는 도구입니다. 긴 작업을 맡겨두고 다른 일을 하세요.

5개 AI 코딩 도구 지원

Claude Code, Codex CLI, Gemini CLI, Aider, OpenCode — 프로젝트별 도구 선택 가능.

프롬프트 자동 추출

작업 완료 시 마지막 유저 프롬프트를 자동 추출하여 알림에 포함합니다.

프로젝트별 관리

프로젝트별로 다른 도구와 토픽을 설정하여 채널을 분리할 수 있습니다.

지원 도구

CLI 도구	`cli_tool` 값	파싱 방식
Claude Code	`claude-code`	JSONL, type:"user"
Codex CLI (OpenAI)	`codex-cli`	JSONL, role:"user"
Gemini CLI (Google)	`gemini-cli`	JSON/JSONL, role:"user"
Aider	`aider`	텍스트 마지막 줄
OpenCode	`opencode`	SQLite 쿼리

알림 내용은 각 도구의 대화 기록에서 마지막 유저 프롬프트를 자동 추출합니다. 프롬프트를 찾지 못하면 최근 git commit 메시지로 폴백합니다.

사전 요구사항

•jq — JSON 처리 (필수, python3으로 폴백 가능)
•curl — HTTP 요청
•AI 코딩 CLI 도구 — 위 목록 중 하나 이상
•VibeShell 앱 (iOS/Android) — 토픽 ID 확인용
•sqlite3 — OpenCode 사용 시 필요

# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

설치

원라인 설치

터미널에 붙여넣기

curl -fsSL https://www.wevesolutions.co.kr/downloads/hook/install.sh | bash -s -- --install

프롬프트에 따라 입력하세요:

프로젝트명 — 알림에 표시될 이름 (예: my-project)

프로젝트 경로 — AI 코딩 도구를 실행하는 디렉토리 (기본: 현재 디렉토리)

AI 코딩 도구 — 해당 프로젝트에서 사용하는 도구 선택 (Claude Code, Codex CLI, Gemini CLI, Aider, OpenCode)

토픽 ID — VibeShell 앱 설정 > Push 알림에서 복사 (예: vbs_abc123)

Push 서버 URL — 기본값 https://push.vibeshell.io 사용

다운로드 후 설치

스크립트 다운로드 후 실행

mkdir -p /tmp/vibeshell-hook
curl -fsSL -o /tmp/vibeshell-hook/install.sh https://www.wevesolutions.co.kr/downloads/hook/install.sh
curl -fsSL -o /tmp/vibeshell-hook/hook.sh https://www.wevesolutions.co.kr/downloads/hook/hook.sh
chmod +x /tmp/vibeshell-hook/install.sh /tmp/vibeshell-hook/hook.sh

cd /tmp/vibeshell-hook
./install.sh --install

수동 설치

자동 설치 없이 직접 설정하고 싶은 경우:

1. 스크립트 다운로드

hook.sh 다운로드

mkdir -p ~/.vibeshell
curl -fsSL -o ~/.vibeshell/hook.sh https://www.wevesolutions.co.kr/downloads/hook/hook.sh
chmod +x ~/.vibeshell/hook.sh

2. 설정 파일 생성

~/.vibeshell/push-config.json

{
  "server_url": "https://push.vibeshell.io",
  "enabled": true,
  "topic_ids": ["vbs_your_topic_id_here"],
  "topic_tokens": {},
  "projects": {
    "my-project": {
      "paths": ["/Users/username/projects/my-project"],
      "enabled": true,
      "cli_tool": "claude-code"
    }
  }
}

3. AI 코딩 도구에 hook 등록

사용하는 도구에 맞게 hook을 등록합니다.

Claude Code — ~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/username/.vibeshell/hook.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

이미 settings.json이 있으면 hooks.Stop 배열에 추가합니다. 기타 도구는 각 도구의 hook/event 시스템에 ~/.vibeshell/hook.sh를 등록하세요.

💡 topic_tokens는 install.sh 실행 시 서버에서 자동 발급됩니다. 수동 설치 시:

curl -s -X POST https://push.vibeshell.io/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{"topic":"vbs_your_topic_id_here"}'

동작 방식

AI 코딩 도구가 작업을 완료하고 hook을 실행합니다.

hook.sh가 ~/.vibeshell/push-config.json을 로드합니다.

현재 작업 디렉토리가 등록된 프로젝트 경로와 매칭되는지 확인합니다.

프로젝트의 cli_tool 설정에 따라 대화 기록에서 마지막 유저 프롬프트를 추출합니다.

topic_tokens에서 해당 토픽의 인증 토큰을 조회합니다.

push.vibeshell.io로 알림 데이터를 전송합니다. (Bearer 토큰 첨부)

VibeShell 앱에서 푸시 알림을 수신합니다.

알림 내용 우선순위

해당 CLI 도구의 대화 기록에서 마지막 유저 프롬프트 (100자 제한)
최근 git commit 메시지 (프롬프트 추출 실패 시)
"작업 완료" (git 기록도 없을 때)

• 등록되지 않은 경로에서는 알림을 보내지 않습니다.
• 요청 실패 시 무시됩니다. (타임아웃 5초, 백그라운드 실행)

CLI 도구별 프롬프트 추출

도구	대화 기록 위치	추출 방식
Claude Code	`~/.claude/projects/<경로>/*.jsonl`	type:"user" content 추출
Codex CLI	`~/.codex/sessions/*/.jsonl`	role:"user" 메시지 추출
Gemini CLI	`~/.gemini/tmp/<hash>/chats/session-*`	role:"user" JSON/JSONL 추출
Aider	`<프로젝트>/.aider.input.history`	마지막 비어있지 않은 줄
OpenCode	`~/.local/share/opencode/opencode.db`	SQLite 최근 user 메시지 쿼리

설정 구조

~/.vibeshell/push-config.json

{
  "server_url": "https://push.vibeshell.io",
  "enabled": true,
  "topic_ids": ["vbs_your_topic_id_here"],
  "topic_tokens": {},
  "projects": {
    "my-project": {
      "paths": ["/Users/username/projects/my-project"],
      "enabled": true,
      "cli_tool": "claude-code"
    }
  }
}

server_url

푸시 알림 서버 주소. 기본값 https://push.vibeshell.io

enabled

전역 활성화/비활성화 스위치

topic_ids

전역 토픽 ID 배열. 프로젝트별 설정이 없으면 이 토픽으로 알림을 보냅니다.

topic_tokens

토픽별 인증 토큰 (서버에서 자동 발급, install.sh 실행 시 생성)

projects

프로젝트별 설정 (이름 → 설정)

projects.*.paths

해당 프로젝트로 인식할 디렉토리 경로 목록

projects.*.enabled

프로젝트별 활성화/비활성화

projects.*.cli_tool

AI 코딩 도구 (claude-code, codex-cli, gemini-cli, aider, opencode). 미지정 시 claude-code

projects.*.topic_ids

프로젝트별 토픽 오버라이드 (없으면 전역 사용)

여러 프로젝트 설정 예시

프로젝트마다 다른 AI 코딩 도구를 사용하는 경우:

프로젝트별 도구 + 토픽 분리

{
  "server_url": "https://push.vibeshell.io",
  "enabled": true,
  "topic_ids": ["vbs_9b585155aaf8"],
  "topic_tokens": {
    "vbs_9b585155aaf8": "auto-generated...",
    "vbs_separate_topic": "auto-generated..."
  },
  "projects": {
    "vibe-shell": {
      "paths": ["/Users/dev/projects/vibe-shell"],
      "enabled": true,
      "cli_tool": "claude-code"
    },
    "my-api": {
      "paths": ["/Users/dev/projects/my-api"],
      "enabled": true,
      "cli_tool": "codex-cli",
      "topic_ids": ["vbs_separate_topic"]
    },
    "data-pipeline": {
      "paths": ["/Users/dev/projects/data-pipeline"],
      "enabled": true,
      "cli_tool": "aider"
    },
    "weekend-project": {
      "paths": ["/Users/dev/weekend/app"],
      "enabled": false,
      "cli_tool": "gemini-cli"
    }
  }
}

토픽 ID 확인

토픽 ID는 VibeShell 앱에서 확인할 수 있습니다:

1.VibeShell 앱 실행

2.설정 → Push 알림

3.토픽 ID 복사 (vbs_ 접두사)

설정 관리

대화형 메뉴로 프로젝트, 토픽, 서버 설정을 관리할 수 있습니다:

# 대화형 관리 메뉴 실행
curl -fsSL https://www.wevesolutions.co.kr/downloads/hook/install.sh | bash

# 또는 로컬에 저장해두고 사용
~/.vibeshell/manage.sh

💡 최초 설치 시 manage.sh로 복사해두면 편리합니다:

curl -fsSL -o ~/.vibeshell/manage.sh https://www.wevesolutions.co.kr/downloads/hook/install.sh
chmod +x ~/.vibeshell/manage.sh

메뉴 항목:

• 프로젝트 추가/삭제/활성화 토글 (CLI 도구 선택 포함)
• 토픽 ID 추가/교체/삭제
• 서버 URL 변경
• 인증 토큰 갱신
• Hook 스크립트 업데이트

업데이트

hook.sh를 최신 버전으로 업데이트:

curl -fsSL -o ~/.vibeshell/hook.sh https://www.wevesolutions.co.kr/downloads/hook/hook.sh
chmod +x ~/.vibeshell/hook.sh

트러블슈팅

알림이 오지 않는 경우

1. 설정 확인

cat ~/.vibeshell/push-config.json
# enabled: true, server_url, topic_ids, cli_tool 확인

2. 경로 매칭 확인

pwd
# 이 경로가 config의 paths 중 하나로 시작해야 함

3. 수동 테스트

curl -X POST https://push.vibeshell.io/api/v1/push \
  -H "Content-Type: application/json" \
  -d '{"topic":"vbs_your_topic","project":"test","summary":"테스트 알림"}'

4. Hook 등록 확인 (Claude Code)

cat ~/.claude/settings.json | jq '.hooks.Stop'

5. Hook 스크립트 권한 확인

ls -la ~/.vibeshell/hook.sh
chmod +x ~/.vibeshell/hook.sh

6. CLI 도구 설정 확인

jq '.projects | to_entries[] | {name: .key, cli_tool: .value.cli_tool}' \
  ~/.vibeshell/push-config.json

7. OpenCode 사용 시 — sqlite3 설치 확인

command -v sqlite3 && echo "OK" || echo "sqlite3 설치 필요"

401 Unauthorized 오류

인증 토큰이 없거나 잘못된 경우 발생합니다.

# 토큰 상태 확인
jq '.topic_tokens' ~/.vibeshell/push-config.json

# 토큰 갱신 (manage.sh 메뉴 6번)
~/.vibeshell/manage.sh

# 또는 수동으로 특정 토픽 토큰 발급
TOKEN=$(curl -s -X POST https://push.vibeshell.io/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{"topic":"vbs_your_topic"}' | jq -r '.token')
jq --arg t "vbs_your_topic" --arg tok "$TOKEN" \
  '.topic_tokens[$t] = $tok' ~/.vibeshell/push-config.json \
  > /tmp/pc.json && mv /tmp/pc.json ~/.vibeshell/push-config.json

알림 내용이 프롬프트가 아닌 경우

cli_tool 설정이 실제 사용하는 도구와 일치하는지 확인하세요. 프롬프트 추출에 실패하면 git commit 메시지로 폴백됩니다.

# 프로젝트별 cli_tool 확인
jq '.projects | to_entries[] | "\(.key): \(.value.cli_tool // "claude-code")"' \
  ~/.vibeshell/push-config.json

# cli_tool 변경
jq '.projects["my-project"].cli_tool = "codex-cli"' \
  ~/.vibeshell/push-config.json > /tmp/pc.json \
  && mv /tmp/pc.json ~/.vibeshell/push-config.json

특정 프로젝트만 알림 끄기

~/.vibeshell/manage.sh
# 또는 직접 수정
jq '.projects["project-name"].enabled = false' \
  ~/.vibeshell/push-config.json > /tmp/pc.json \
  && mv /tmp/pc.json ~/.vibeshell/push-config.json

전체 알림 끄기

jq '.enabled = false' ~/.vibeshell/push-config.json \
  > /tmp/pc.json && mv /tmp/pc.json ~/.vibeshell/push-config.json

파일 목록

hook.sh

AI 코딩 도구 hook 스크립트

install.sh

대화형 설치/관리 스크립트

config.example.json

설정 파일 예시

활용방법 VibeShell 소개 고객지원