claude-code-monitor: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

npm run dev           # 開発モード（ホットリロード付き）
npm run build         # TypeScriptコンパイル
npm start             # コンパイル済みJSを実行

# テスト
npm run test          # テスト実行（単発）
npm run test:watch    # テスト実行（ウォッチモード）
npm run test:coverage # カバレッジ付きテスト
npx vitest tests/handler.test.ts           # 特定ファイルのテスト
npx vitest -t "updateSession"              # 特定テスト名で絞り込み

# コード品質
npm run lint          # biomeでリントチェック
npm run lint:fix      # リント自動修正
npm run format        # コードフォーマット
npm run typecheck     # 型チェックのみ

フックイベントのテスト

# stdinからJSONを渡してフック処理をテスト
echo '{"session_id":"test-123","cwd":"/tmp"}' | npx tsx src/bin/ccm.tsx hook PreToolUse

Architecture

Claude Codeの複数セッションをリアルタイム監視するmacOS専用CLIツール。Ink（React for CLI）を使用したTUIとファイルベースの状態管理で動作する。

重要なファイルパス

• ~/.claude-monitor/sessions.json - セッション状態の永続化ファイル
• ~/.claude/settings.json - Claude Codeのフック設定（ccm setupで自動設定）
• ~/.claude/projects/*/TRANSCRIPT.md - 各セッションの会話履歴

データフロー

1. Hook受信: Claude Codeがフックイベント（PreToolUse, PostToolUse, Notification, Stop, UserPromptSubmit）を発火
2. 状態更新: ccm hook <event> コマンドがstdinからJSONを受け取り、~/.claude-monitor/sessions.json を更新
3. UI更新: chokidarでファイル変更を検知し、Dashboardコンポーネントが再描画
4. モバイルWeb同期: WebSocketで接続中のクライアントにセッション更新をブロードキャスト

ディレクトリ構成

• src/bin/ccm.tsx - CLIエントリーポイント（Commanderでコマンド定義）
• src/hook/handler.ts - フックイベント処理（stdin読み取り→状態更新）
• src/store/file-store.ts - セッション状態の永続化（JSON読み書き、TTY生存確認）
• src/setup/index.ts - ~/.claude/settings.json へのフック自動設定
• src/server/index.ts - HTTP + WebSocketサーバー（モバイルWeb用）
• src/components/ - InkベースのReactコンポーネント（Dashboard, SessionCard, Spinner）
• src/hooks/useSessions.ts - ファイル変更監視付きのReactフック
• src/hooks/useServer.ts - モバイルサーバー起動用フック
• src/utils/focus.ts - AppleScriptによるターミナルフォーカス機能
• src/utils/status.ts - ステータス表示ユーティリティ
• src/types/index.ts - 型定義（HookEvent, Session, SessionStatus, StoreData）
• public/index.html - モバイルWeb UI（静的HTML）