Skip to content

README.md

Latest commit

 

History

History
193 lines (150 loc) · 7.06 KB

README.md

File metadata and controls

193 lines (150 loc) · 7.06 KB
Raw

ClaudeMonitor

image

Claude Code 세션을 모니터링하는 macOS 오버레이 앱.
여러 Claude Code 세션을 캐릭터로 화면에 띄워두고, 작업 완료 시 말풍선 알림을 받을 수 있습니다.

macOS Swift

Features

  • 항상 최상위에 떠있는 오버레이 캐릭터 (모든 Space + 전체화면에서 표시)
  • 세션별 커스텀 GIF 아바타
  • Claude Code 응답 완료 / 권한 요청 시 말풍선 알림 + 사운드
  • 말풍선/캐릭터 클릭 시 해당 세션의 터미널 탭으로 이동 (Claude 데스크톱 앱 세션은 앱 활성화)
  • 드래그로 위치 이동
  • 캐릭터 크기 설정 (Small / Medium / Large)
  • 메인 색상 설정 (9가지 프리셋 색상)
  • 다양한 터미널 지원: iTerm2, Terminal.app, cmux, Warp, Ghostty, Kitty, Alacritty, tmux
  • Claude 데스크톱 앱 안에서 실행하는 Claude Code 세션도 지원 (session_id 기반 라우팅)
  • Settings UI에서 세션/터미널/크기/색상 설정
  • /monitor 슬래시 커맨드로 세션 자동 등록
Vector

Install

git clone https://github.com/jeongchoyi/ClaudeMonitor.git
cd ClaudeMonitor
swift build -c release
.build/release/ClaudeMonitor &

로그인 시 자동 실행하려면 System Settings > General > Login Items에 추가하세요.

Setup

1. Claude Code Hook 설정

~/.claude/settings.json에 추가:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/ClaudeMonitor/Scripts/register-hook.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/ClaudeMonitor/Scripts/notify-hook.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/ClaudeMonitor/Scripts/notify-hook.sh"
          }
        ]
      }
    ]
  }
}

/path/to/ClaudeMonitor/를 실제 설치 경로로 변경하세요.

  • SessionStart: 세션 시작 시 자동으로 ClaudeMonitor에 등록됩니다. 세션이 종료되면 자동으로 사라집니다.
  • Stop: Claude 응답이 완전히 끝났을 때(툴 실행 중/중간 단계엔 fire 안 됨) 말풍선을 띄웁니다. "진짜 다 끝났을 때만" 알림 받고 싶으면 이것만 써도 됩니다.
  • Notification: Claude가 사용자 입력을 기다릴 때(권한 요청 / 60초 idle) 말풍선을 띄웁니다. 중간에 Allow/Deny 확인 필요한 경우를 놓치지 않으려면 Stop과 함께 쓰세요.

2. 터미널 설정

캐릭터 우클릭 → Settings에서 사용 중인 터미널을 선택합니다.

터미널 탭 전환 필요 권한
iTerm2 CWD 기반 자동 매칭 Automation (AppleScript)
Terminal.app 탭 이름 기반 매칭 Automation (AppleScript)
cmux 앱 활성화 없음
tmux pane CWD 기반 매칭 없음
Warp 앱 활성화 없음
Ghostty 앱 활성화 없음
Kitty 앱 활성화 없음
Alacritty 앱 활성화 없음

iTerm2/Terminal.app 사용 시: 처음 클릭할 때 macOS가 자동화 권한을 요청합니다. System Settings > Privacy & Security > Automation에서 ClaudeMonitor가 해당 터미널을 제어할 수 있도록 허용하세요.

Claude 데스크톱 앱에서 Claude Code를 사용하는 경우: 이 세션은 제어 터미널(tty)이 없어 자동으로 감지됩니다. 캐릭터를 클릭하면 Claude 데스크톱 앱을 앞으로 가져옵니다(앱이 스크립팅을 제공하지 않아 특정 대화 탭까지 지정하지는 못합니다). 말풍선은 session_id로 라우팅되므로, 같은 폴더의 다른 세션과 섞이지 않습니다.

3. 세션 등록

Hook 설정을 완료하면 Claude Code 세션 시작 시 자동으로 등록됩니다. 세션 종료 후에는 자동으로 사라집니다.

수동으로 등록하려면:

  • Settings UI: 캐릭터 우클릭 → Settings → Add Session (수동 등록 세션은 자동 삭제되지 않음)
  • curl: curl -s -X POST http://localhost:9877/register -H "Content-Type: application/json" -d '{"name":"my-session","cwd":"/path/to/project"}'

4. 아바타 설정

Settings에서 GIF/PNG/JPG 파일을 선택하면 ~/.claude-monitor/avatars/에 자동 복사됩니다. GIF 파일은 애니메이션으로 표시됩니다.

5. 캐릭터 크기

Settings의 Size 선택에서 Small / Medium / Large 중 선택할 수 있습니다 (기본값: Small). 캐릭터 본체, 이름 라벨, 오버레이 창 크기가 함께 스케일됩니다.

6. 메인 색상

Settings의 Color에서 9가지 프리셋 색상 중 하나를 선택할 수 있습니다 (기본값: Purple). 캐릭터 테두리, 이름 라벨, 말풍선 테두리 색상에 적용됩니다.

Usage

동작 결과
캐릭터 클릭 해당 세션 터미널 활성화 (Claude 데스크톱 앱 세션은 Claude 앱 활성화)
말풍선 클릭 터미널 활성화 + 말풍선 닫기
드래그 위치 이동
우클릭 / Ctrl+클릭 컨텍스트 메뉴 (Settings, New Session, Reset Position, Quit)

터미널로 전환하면 말풍선이 자동으로 사라집니다.

API

ClaudeMonitor는 localhost:9877에서 HTTP 서버를 실행합니다.

알림 보내기:

curl -X POST http://localhost:9877/notify \
  -H "Content-Type: application/json" \
  -d '{"cwd":"/path/to/project","message":"Build done!"}'

세션 등록:

curl -X POST http://localhost:9877/register \
  -H "Content-Type: application/json" \
  -d '{"name":"session-name","cwd":"/path/to/project"}'

Config

설정 파일: ~/.claude-monitor/config.json
아바타 저장: ~/.claude-monitor/avatars/
앱 아이콘: ~/.claude-monitor/icon.png (선택사항)

{
  "terminal": "iTerm2",
  "characterSize": "Small",
  "mainColor": "Purple",
  "sessions": [
    {
      "name": "my-project",
      "cwdPattern": "/Users/me/projects/my-project",
      "gifPath": "/Users/me/.claude-monitor/avatars/avatar.gif",
      "order": 0,
      "tty": "ttys036",
      "sessionId": "1f385257-62f9-4541-b594-4d095d215c21"
    }
  ]
}
  • terminal 값: iTerm2, Terminal, cmux, tmux, Warp, Ghostty, Kitty, Alacritty
  • characterSize 값: Small, Medium, Large
  • mainColor 값: Red, Orange, Yellow, Green, Blue, Indigo, Purple, Black, Pink
  • tty / sessionId: 세션 자동 등록 시 채워집니다. 말풍선·클릭 라우팅 식별자로, 비어 있으면 cwd로 폴백합니다 (sessionId가 가장 우선).