claude-code-watcher 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 정재남[ 플레이스여행서비스개발 ]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# claude-code-watcher (ccw)
+
+![screenshot](./screenshot.png)
+
+VS Code 터미널에서 실행 중인 Claude Code 세션을 실시간으로 모니터링하는 CLI 대시보드입니다.
+
+여러 개의 Claude Code 세션을 동시에 열어 두고 작업할 때, 각 세션의 현재 상태(작업 중 / 대기 중 / 알림)를 한 화면에서 확인할 수 있습니다.
+
+## 기능
+
+- **실시간 세션 목록** — 열려 있는 모든 Claude Code 세션의 상태를 TTY 오름차순으로 표시
+- **상태 추적** — `working` / `waiting` / `notification` / `stale` 상태 자동 전환
+- **서브에이전트 추적** — Agent 툴 실행 중인 서브에이전트 수 표시
+- **알림** — `Stop`(응답 완료) 또는 `Notification`(권한 요청) 이벤트 발생 시 소리 알림 (사운드 커스터마이징 가능)
+- **세션 상세보기** — 선택한 세션의 마지막 메시지, 경로, 타임스탬프 등 상세 정보
+- **프로세스 재시작** — `R` 키로 대시보드 자체를 재실행
+
+## 요구사항
+
+- Node.js 18 이상
+- Claude Code CLI
+
+## 설치
+
+```bash
+npm i -g claude-code-watcher
+
+# 훅 등록 (최초 1회)
+ccw setup
+```
+
+`ccw setup`은 다음 작업을 수행합니다.
+
+- `~/.claude/hooks/` 에 훅 스크립트 복사
+- `~/.claude/settings.json` 에 Claude Code 라이프사이클 훅 등록
+- `~/.claude/dashboard/active/` 디렉토리 생성
+
+## 사용법
+
+```bash
+# 1. Claude Code 세션 시작 (프로젝트 디렉토리에서)
+claude
+
+# 2. 별도 터미널 탭에서 대시보드 실행
+ccw
+```
+
+### 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `ccw` / `ccw start` | 인터랙티브 대시보드 실행 |
+| `ccw setup` | 훅 설치 및 디렉토리 생성 |
+| `ccw status` | 일회성 세션 목록 출력 |
+| `ccw sessions` | 세션 목록 JSON 출력 |
+| `ccw /sound` | 알림 사운드 설정 보기/변경 |
+| `ccw help` | 도움말 출력 |
+
+### 사운드 커스터마이징
+
+알림 이벤트별로 macOS 시스템 사운드를 변경할 수 있습니다.
+
+```bash
+# 현재 설정 및 사용 가능한 사운드 목록 보기
+ccw /sound
+
+# Notification(권한 요청) 사운드 변경
+ccw /sound noti Funk
+
+# Stop(응답 완료) 사운드 변경
+ccw /sound stop Blow
+```
+
+사용 가능한 사운드: `Basso`, `Blow`, `Bottle`, `Frog`, `Funk`, `Glass`, `Hero`, `Morse`, `Ping`, `Pop`, `Purr`, `Sosumi`, `Submarine`, `Tink`
+
+설정은 `~/.claude/dashboard/config.json`에 저장되며, 대시보드 재시작 없이 즉시 적용됩니다.
+
+### 대시보드 키 조작
+
+| 키 | 동작 |
+|----|------|
+| `↑` / `↓` | 세션 선택 이동 |
+| `Enter` | 상세보기 ↔ 목록 전환 |
+| `r` | 데이터 새로고침 |
+| `R` | 대시보드 프로세스 재시작 |
+| `q` | 종료 |
+
+## 세션 상태
+
+| 상태 | 색상 | 설명 |
+|------|------|------|
+| `working` | 노랑 | Claude가 응답을 처리 중 |
+| `waiting` | 초록 | 사용자 입력 대기 중 |
+| `notification` | 청록 | 권한 요청 등 알림 발생 |
+| `stale` | 회색 | 10분 이상 업데이트 없음 |
+| `error` | 빨강 | 오류 발생 |
+
+## 동작 원리
+
+Claude Code의 라이프사이클 훅을 통해 세션 상태를 추적합니다.
+
+```
+Claude Code 이벤트 발생
+       ↓
+~/.claude/hooks/session-tracker.mjs 실행
+       ↓
+~/.claude/dashboard/active/<sessionId>.json 업데이트
+       ↓
+ccw 대시보드가 파일 변경 감지 → 화면 갱신
+```
+
+등록되는 훅 이벤트:
+
+| 이벤트 | 전환 상태 |
+|--------|-----------|
+| `SessionStart` | `waiting` |
+| `UserPromptSubmit` | `working` |
+| `PreToolUse` / `PostToolUse` | `notification` → `working` 복원 |
+| `Stop` | `waiting` + 알림 |
+| `Notification` | `notification` (working 중일 때만) |
+| `SubagentStart` / `SubagentStop` | 서브에이전트 목록 관리 |
+| `SessionEnd` | 세션 파일 삭제 |
+
+## 알려진 제한사항
+
+### 사용자 인터럽트 미지원
+
+Claude Code 응답 중 Esc 키로 취소("Interrupted · What should Claude do instead?")를 하면 **상태가 `working`으로 유지됩니다.**
+
+현재 Claude Code 훅 API는 사용자 취소 이벤트를 제공하지 않습니다. `Stop` 훅은 자연 완료 시에만 발생하며, 인터럽트 시에는 발생하지 않습니다. 다음 프롬프트를 제출하면 `working` 상태로 정상 복귀합니다.
+
+### 강제 종료 세션
+
+Claude Code를 강제 종료(`kill`, 터미널 강제 닫기)하면 `SessionEnd` 훅이 실행되지 않아 세션 파일이 남을 수 있습니다. 대시보드 실행 시 프로세스 생존 여부를 자동으로 확인하여 정리합니다.
+
+
+## 라이선스
+
+MIT

package/bin/ccw.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const command = args[0] || 'start';
+
+const commands = {
+  start: () => import(join(__dirname, '../src/commands/start.mjs')),
+  setup: () => import(join(__dirname, '../src/commands/setup.mjs')),
+  status: () => import(join(__dirname, '../src/commands/status.mjs')),
+  sessions: () => import(join(__dirname, '../src/commands/sessions.mjs')),
+  help: () => import(join(__dirname, '../src/commands/help.mjs')),
+  '--help': () => import(join(__dirname, '../src/commands/help.mjs')),
+  '-h': () => import(join(__dirname, '../src/commands/help.mjs')),
+  '/sound': () => import(join(__dirname, '../src/commands/sound.mjs')),
+};
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "ccw help" for usage.');
+  process.exit(1);
+}
+
+commands[command]().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/hooks/session-tracker.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ACTIVE_DIR = process.env.ACTIVE_DIR
+  ?? path.join(process.env.HOME ?? '', '.claude', 'dashboard', 'active');
+
+// Read JSON payload from stdin synchronously
+let raw;
+try {
+  raw = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const sessionId  = raw.session_id       ?? '';
+const hookEvent  = raw.hook_event_name  ?? '';
+const cwd        = raw.cwd              ?? '';
+const transcript = raw.transcript_path  ?? '';
+
+if (!sessionId) process.exit(0);
+
+const sessionFile = path.join(ACTIVE_DIR, `${sessionId}.json`);
+
+const now = new Date();
+const pad = n => String(n).padStart(2, '0');
+const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} `
+                + `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+
+// Read existing session data
+let existing = {};
+try {
+  existing = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+} catch { /* new session or parse error */ }
+
+// Fields that fall back to existing values when absent from the current event payload
+const resolvedCwd        = cwd        || existing.cwd        || '';
+const resolvedTranscript = transcript || existing.transcript || '';
+const project = resolvedCwd ? path.basename(resolvedCwd) : (existing.project ?? 'unknown');
+
+// Capture ppid once; reuse on subsequent events (used to detect orphaned sessions)
+const ppid = existing.ppid ?? process.ppid;
+
+// Capture TTY once; reuse on subsequent events
+let ttyPath = existing.tty ?? '';
+if (!ttyPath) {
+  try {
+    const dev = execFileSync('ps', ['-o', 'tty=', '-p', String(process.ppid)], { encoding: 'utf8' }).trim();
+    if (dev && dev !== '??') ttyPath = `/dev/${dev}`;
+  } catch { /* ignore */ }
+}
+
+let startedAt    = existing.startedAt    ?? timestamp;
+let message      = existing.message      ?? '';
+let lastResponse = existing.lastResponse ?? '';
+let alertAt      = existing.alertAt      ?? '';
+let alertEvent   = existing.alertEvent   ?? '';
+let subagents    = Array.isArray(existing.subagents) ? existing.subagents : [];
+let status;
+
+switch (hookEvent) {
+  case 'SessionStart':
+    status    = 'waiting';
+    message   = 'Session started';
+    startedAt = timestamp;
+    break;
+
+  case 'UserPromptSubmit': {
+    status  = 'working';
+    const prompt = raw.prompt ?? '';
+    message = prompt ? prompt.slice(0, 100) : 'Processing...';
+    break;
+  }
+
+  case 'PreToolUse':
+  case 'PostToolUse': {
+    // Restore to 'working' from 'notification' (permission granted).
+    // Preserve 'waiting' and other states to avoid spurious transitions after Stop.
+    const cur = existing.status ?? 'working';
+    status  = (cur === 'notification' || cur === 'working') ? 'working' : cur;
+    message = existing.message ?? 'Processing...';
+    break;
+  }
+
+  case 'Stop': {
+    status       = 'waiting';
+    alertAt      = timestamp;
+    alertEvent   = 'Stop';
+    lastResponse = (raw.last_assistant_message ?? '').slice(0, 200);
+    message      = lastResponse ? lastResponse.slice(0, 100) : 'Ready';
+    subagents    = [];
+    break;
+  }
+
+  case 'Notification': {
+    // Only elevate to 'notification' when Claude is actively working (permission request).
+    // If already waiting, this is a background completion ping — keep 'waiting'.
+    const prevStatus = existing.status ?? 'waiting';
+    status     = prevStatus === 'working' ? 'notification' : prevStatus;
+    alertAt    = timestamp;
+    alertEvent = 'Notification';
+    if (status === 'notification') {
+      message = (raw.message ?? 'Notification').slice(0, 100);
+    }
+    break;
+  }
+
+  case 'SessionEnd':
+    try { fs.unlinkSync(sessionFile); } catch { /* already gone */ }
+    process.exit(0);
+    break;
+
+  case 'SubagentStart': {
+    status  = 'working';
+    message = existing.message ?? 'Processing...';
+    const agentId   = raw.agent_id   ?? '';
+    const agentType = raw.agent_type ?? '';
+    if (agentId && !subagents.some(s => s.agentId === agentId)) {
+      subagents.push({ agentId, agentType, status: 'working', startedAt: timestamp, completedAt: '' });
+    }
+    break;
+  }
+
+  case 'SubagentStop': {
+    status    = 'working';
+    message   = existing.message ?? 'Processing...';
+    const agentId = raw.agent_id ?? '';
+    subagents = subagents.filter(s => s.agentId !== agentId);
+    break;
+  }
+
+  default:
+    status = existing.status ?? 'waiting';
+}
+
+fs.mkdirSync(ACTIVE_DIR, { recursive: true });
+
+const data = {
+  session:      sessionId,
+  project,
+  cwd:          resolvedCwd,
+  status,
+  message,
+  lastResponse,
+  sessionName:  existing.sessionName ?? '',
+  transcript:   resolvedTranscript,
+  updated:      timestamp,
+  startedAt,
+  tty:          ttyPath,
+  ppid,
+  alertAt,
+  alertEvent,
+  subagents,
+};
+
+// Atomic write: write to tmp then rename
+const tmp = `${sessionFile}.tmp.${process.pid}`;
+try {
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+  fs.renameSync(tmp, sessionFile);
+} catch (err) {
+  try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+  throw err;
+}

package/hooks/session-tracker.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec node "$(dirname "$0")/session-tracker.mjs"