Claude Code 모니터링을 위한 Raycast 확장을 만들었습니다

평범한 어느 오후였습니다.

터미널에서 Claude Code 세션 5개가 동시에 돌아가고 있었습니다. 하나는 블로그를 수정하고, 하나는 백엔드 API를 작성하고, 하나는 코드 리뷰를 도와주고, 나머지 둘은 어디까지 진행됐는지도 모르는 상태였습니다. 이리저리 전환하면서도, 어떤 세션이 내 입력을 기다리고 있는지, 어떤 것이 아직 작업 중인지, 어떤 것이 이미 끝났는지 도무지 구분할 수가 없었습니다.

"모든 세션의 상태를 한눈에 볼 수 있는 곳이 있으면 좋겠는데."

이것저것 찾아봤는데, Claude Code를 모니터링하는 도구가 몇 가지 있긴 했지만 제 기대에 완벽히 부합하는 건 없었습니다. 단순히 세션 상태만 보는 게 아니라, Claude Code의 모든 것을 통합 관리할 수 있는 곳이 필요했습니다. 세션, Skills, MCP 서버, 플러그인까지. 게다가 어떤 터미널에서, 어떤 에디터에서 열었든 상관없이 클릭 한 번으로 바로 해당 세션으로 돌아갈 수 있어야 했습니다.

찾을 수 없다면, 직접 만들면 됩니다.

AI 시대: 필요하면 직접 만든다

최근 2년간 가장 크게 느낀 점은, AI가 "도구를 원하는 것"과 "도구를 가지는 것" 사이의 거리를 완전히 바꿔놓았다는 것입니다.

예전에는 아이디어가 있으면 누군가 만들어주길 기다리거나, 새로운 프레임워크를 몇 달 동안 배워서 직접 처음부터 만들어야 했습니다. 대부분의 아이디어는 결국 "그냥 되는 대로 쓰자"로 끝나곤 했죠.

지금은 다릅니다. 요구사항만 명확하게 설명하면, Claude Code가 나머지를 해결해줍니다.

이동

이전에 AI로 Raycast 확장을 두 개 만든 적이 있어서, 이번 새로운 필요가 생겼을 때 자연스럽게 바로 작업에 착수했습니다. 첫 번째 코드 줄부터 기능이 기본적으로 완성될 때까지, 하룻밤이면 충분했습니다.

아직 Raycast를 모르신다면, 제가 이전에 쓴 《Raycast: 내가 가장 좋아하는 Mac 소프트웨어》를 참고해보세요. 간단히 말하면, macOS의 생산성 허브입니다. 일상의 거의 모든 고빈도 작업을 Raycast를 통해 처리합니다. 그래서 Claude Code 모니터링 도구를 만들고 싶었을 때, Raycast가 가장 자연스러운 선택이었습니다. 메뉴바 상주, 키보드 우선 조작, 네이티브 macOS 성능 — "수시로 한번 훑어보기"라는 사용 시나리오에 딱 맞았습니다.

AI 시대에는, 누군가 만들어주길 기다릴 필요가 없습니다 — 바로 당신이 그 "누군가"입니다.

불편함: 왜 이 도구가 필요한가

Claude Code를 많이 쓸수록, 소소한 마찰이 쌓여갑니다. 하나하나 보면 큰 문제는 아니지만, 합쳐지면 매일 주의력을 소모하게 됩니다.

다중 세션 상태를 볼 수 없고, 돌아가기도 번거롭다

가장 직접적인 불편함입니다. Claude Code는 터미널에서 실행되고, 하나의 창이 하나의 세션입니다. 여러 프로젝트를 동시에 여는 건 흔한 일입니다. 블로그 스타일 수정, 플러그인 기능 추가, 유틸 라이브러리 버그 수정 등. 하지만 문제는, 어떤 세션이 입력을 기다리는지, 어떤 것이 아직 실행 중인지, 어떤 것이 이미 끝났는지 전혀 알 수가 없다는 것입니다.

더 성가신 건 전환입니다. 블로그 프로젝트 세션은 Zed에서, 플러그인 프로젝트는 Warp에서, 유틸 라이브러리 세션도 백그라운드에서 돌아가고 있습니다. 돌아가고 싶다면? 먼저 어떤 프로젝트가 어떤 창에 있었는지 떠올리고, 여러 터미널 중에서 찾아야 합니다. 제가 필요한 건 이것입니다: 세션이 어디서 열렸든 상관없이, 클릭 한 번으로 바로 돌아갈 수 있는 것.

토큰 사용량에 대한 인식이 없다

매일 Claude Code로 코드를 작성하면서 토큰이 계속 소모됩니다. CLI에 /cost 명령어가 있긴 하지만, 구독 사용자에게는 "구독 크레딧을 사용 중입니다"라고만 알려줄 뿐 구체적인 수치는 보여주지 않습니다. 어떤 프로젝트가 가장 많이 사용하는지? 오늘 사용량이 어제와 비교하면 어떤지? 모델별 소비 분포는 어떤지? 이런 질문들에 대한 답이 전혀 없습니다.

플러그인 업데이트와 관리가 번거롭다

Claude Code의 플러그인 생태계가 점점 풍부해지면서 십여 개의 플러그인을 설치해뒀습니다. 하지만 관리 방식이 매우 원시적입니다. 어떤 플러그인이 설치되어 있는지, 버전이 뭔지, 업데이트가 있는지 확인하려면 설정 파일을 뒤져야 합니다. 활성화, 비활성화, 업데이트, 제거 — 매 단계마다 커맨드라인 작업이 필요합니다.

더 답답한 건 업그레이드 경험입니다. 힘들게 플러그인을 업그레이드했는데, 다음에 Claude Code를 시작하면 이전 버전으로 돌아가 있습니다. 커맨드라인은 "업그레이드 성공"이라고 하지만, 정말로 업그레이드됐는지 확인할 방법이 없습니다. 버전 비교도, 변경 로그도, 현재 모든 플러그인의 실제 버전을 한눈에 볼 수 있는 곳도 없습니다. 플러그인이 많아지면, 관리는 순전히 기억에 의존하는 노동이 됩니다.

Skills와 MCP 서버 상태를 알 수 없다

Skills를 설치한 후, 정말 적용됐는지 어떻게 확인할까요? 사용자 레벨인지 프로젝트 레벨인지? 어떤 플러그인에서 설치된 건지? 더 골치 아픈 건 MCP 서버입니다. 다섯여섯 개를 설정해놨는데, 어떤 것이 연결됐는지, 어떤 것이 재인증이 필요한지, 어떤 것이 아예 연결이 안 되는지 모릅니다. 이런 정보들이 서로 다른 설정 파일에 흩어져 있어, 전체 모습을 한눈에 볼 수 있는 곳이 없습니다.

결국 제가 필요한 건 컨트롤 패널 — 모든 세션 상태, 사용량 분포, 확장 건강도를 한눈에 볼 수 있는 것입니다.

개발 과정

첫 번째 단계: PRD 작성으로 요구사항 명확히 하기

AI로 코드를 작성할 때, 가장 중요한 단계는 오히려 코드 작성이 아니라 요구사항을 명확히 정리하는 것입니다.

먼저 Claude Code에게 PRD(제품 요구사항 문서)를 작성하게 했습니다. 원하는 기능을 하나하나 나열했습니다: 세션 실시간 모니터링, 메뉴바 상주 상태, 사용량 통계 패널, 확장 관리(Plugins + Skills + MCP Servers), 원클릭 이동 및 복원. 각 기능의 예상 인터랙션, 데이터 출처, 표시 방식까지 PRD에 명확히 기술했습니다.

PRD가 완성된 후, 이후의 구현은 문서에 따라 모듈 단위로 진행하면 됐고, Claude Code에게 다시 맥락을 설명할 필요가 거의 없었습니다.

두 번째 단계: 기존 방안 조사

PRD가 확정된 후, Claude Code에게 시장 조사를 시켰습니다: 현재 Claude Code를 모니터링하는 오픈소스 도구에는 어떤 것들이 있는지? 어떻게 구현되어 있는지?

조사 결과, 대부분의 기존 방안의 핵심 접근법은 JSONL 파일 읽기였습니다. Claude Code는 각 세션의 기록을 ~/.claude/projects/ 디렉토리 아래의 .jsonl 파일에 실시간으로 기록합니다. 각 대화 턴의 토큰 수, 사용된 모델, 타임스탬프 등의 정보가 포함되어 있습니다. 이 파일들을 파싱하면 세션의 상세 데이터를 복원할 수 있습니다.

JSONL 데이터는 풍부하지만, 통계 분석에 더 적합합니다 — 토큰 누적, 모델 분포, 프로젝트 비교 같은 것들. 세션의 실시간 상태 추적(누가 입력을 기다리는지, 누가 실행 중인지)을 위해서는 또 다른 데이터 소스가 필요합니다.

여기서 Claude Code Hooks API를 활용했습니다. Hooks는 Claude Code 공식 제공 생명주기 이벤트 메커니즘으로, SessionStart, UserPromptSubmit, PreToolUse, Stop, SessionEnd, Notification 같은 이벤트가 발생할 때 자동으로 스크립트를 실행하도록 등록할 수 있습니다. 이전에 Claude Code를 사용하면서 이미 Hooks를 접해봤기 때문에, 이벤트 기반 상태 추적이 가능하다는 걸 알고 있었습니다.

방향이 명확해졌습니다 — Hooks는 실시간 상태 담당, JSONL은 풍부한 메타데이터 담당. 두 데이터 소스가 상호 보완되어, 완전한 모니터링 솔루션을 구축할 수 있습니다.

왜 Web 패널이나 VS Code 확장이 아닌 Raycast를 선택했느냐? 이유는 간단합니다: Raycast는 원래 제 생산성 허브이고, 메뉴바 상주 아이콘을 지원하며, 아무 창도 열지 않고 한눈에 상태를 확인할 수 있습니다. 키보드 조작이 매끄럽게 이어져 작업 흐름을 끊지 않습니다. 게다가 Raycast 확장 개발은 React + TypeScript를 사용하는데, 제가 매우 익숙한 기술입니다.

세 번째 단계: 하룻밤에 기능 완성

PRD와 기술 방안이 준비되면, 나머지는 Claude Code에게 맡기면 됩니다. 전체 시스템의 데이터 흐름은 두 갈래입니다:

Claude Code 생명주기 이벤트
        │
        ▼
    hook.sh (Bash + 내장 Python)
        │
        ├── 원자적 파일 잠금 (mkdir)
        ├── 이벤트 → 상태 매핑
        ├── 비동기 AI 태그 생성 (Haiku)
        └── 만료 세션 정리
        │
        ▼
    sessions.json (실시간 상태)
        │
        └──────────┐
                   ▼
        Raycast Extension
          useSessions Hook
                   ▲
        ┌──────────┘
        │
    ~/.claude/projects/**/*.jsonl
        │
        └── Chunk-based 정규식 파싱
            (256KB 고정 메모리)

간단히 말하면: Hooks가 실시간 이벤트를 캡처하여 sessions.json에 기록하고, JSONL 파싱이 토큰과 모델 등의 메타데이터를 제공하며, Raycast 확장이 둘을 통합하여 표시합니다. 기술적 디테일 — 원자적 파일 잠금, chunk-based 정규식 파싱, AI 태그 생성, 디스크 캐싱 — 은 모두 Claude Code가 자체적으로 선택한 것이고, 저는 작동하는지 검수만 했습니다.

진짜 재미있었던 건 그 후의 디버깅입니다. 직접 만든 도구로 Claude Code를 모니터링하면서 계속 문제를 발견하고 수정했습니다:

• Subagent가 패널을 도배: 처음 실행하자마자 세션 목록에 모르는 session이 갑자기 잔뜩 나타났습니다. 한참 조사해보니 Claude Code의 하위 에이전트 시작도 Hook을 트리거하고 있었습니다. 하나의 메인 세션이 십여 개의 subagent를 생성하면서 패널이 폭발했습니다. 필터를 추가하여 해결했습니다.
• MCP 가짜 장애: Extensions 페이지에서 여러 MCP가 "Unreachable"로 표시됐지만, 실제로는 잘 돌아가고 있었습니다. stdio 모드의 MCP에 HTTP 헬스체크를 하면 안 됐던 것입니다.
• Worktree 인식 불가: 처음에는 worktree 세션을 전혀 감지하지 못했습니다. .claude/worktrees/ 경로에 대한 정규식 매칭을 추가하여 해결했습니다.
• 플러그인 업데이트가 가짜였다: 확장 관리를 만들면서 Claude Code 자체의 버그를 발견했습니다. 플러그인 업데이트 시 CLI가 원격 저장소에서 최신 버전을 먼저 가져오지 않고, 로컬 캐시와 비교하여 항상 "최신 상태입니다"라고 표시하는 것이었습니다. 확장에서 업데이트 전에 marketplace 저장소를 수동으로 git pull하는 단계를 추가해야 플러그인 업데이트가 실제로 적용됐습니다.

"직접 사용 → 문제 발견 → Claude Code로 수정 → 계속 사용"이라는 순환이었습니다. Claude Code로 Claude Code를 모니터링하는 도구를 만들고, 그 도구로 이 도구를 만드는 Claude Code를 모니터링하는. 완전한 마트료시카였습니다.

네 번째 단계: 아이콘 제작

전체 개발 과정에서 유일하게 수동 작업이 필요했던 부분이 아이콘 제작이었습니다.

먼저 iconfont에서 검색해보니, Claude Code의 작은 게 캐릭터가 바로 눈에 들어왔습니다. 이 디자인은 인지도가 너무 높았습니다:

그런 다음 Raycast 공식 Icon Maker 도구로 배색과 스타일을 선택하여 최종 확장 아이콘을 생성했습니다:

이 단계를 제외하면, 코드 작성부터 Raycast Store 제출까지 전 과정을 Claude Code가 수행했으며, 저는 코드를 한 줄도 직접 수정하지 않았습니다.

기능 소개

세션 모니터링

확장의 핵심 기능입니다. Claude Code Sessions을 열면 모든 세션이 상태별로 그룹화됩니다: Active(실행 중), Waiting for Input(입력 대기), Idle(유휴), Ended(종료).

각 세션에는 프로젝트명, AI가 생성한 태그, 에디터/터미널 유형, Git 브랜치, 지속 시간이 표시됩니다. Git worktree에서 실행 중인 세션이면 worktree 배지도 표시됩니다.

아무 세션이나 선택하고 엔터를 누르면 해당 에디터 창(VS Code, Cursor, Zed, Windsurf 지원)이나 터미널(Terminal, iTerm2, Warp, Ghostty, kitty)로 바로 이동합니다. 종료된 세션은 원클릭으로 resume할 수 있어, 수동으로 claude --resume을 입력할 필요가 없습니다.

메뉴바 상주

Claude Code Status는 메뉴바 아이콘으로, 항상 현재 활성 세션 수를 표시합니다. 상태에 따라 색상이 변합니다: 초록색은 실행 중인 세션이 있음을, 주황색은 입력을 기다리는 세션이 있음을, 노란색은 모두 유휴 상태임을 나타냅니다.

아이콘을 클릭하면 드롭다운 메뉴가 펼쳐져, 모든 세션의 프로젝트명, 터미널 유형, 지속 시간, 상태를 한눈에 볼 수 있습니다. 아무 항목이나 클릭하면 바로 이동합니다.

이것이 제 가장 큰 불편함을 해결해줬습니다 — 더 이상 터미널 창을 하나하나 전환할 필요가 없습니다. 메뉴바를 한번 흘깃 보면, 주황색은 나를 기다리는 것이고, 초록색은 작업 중인 것이고, 나머지는 신경 쓸 필요 없습니다.

게다가 이 상태 표시줄이 생기고 나니, 무의식적으로 항상 초록색을 유지하고 싶어집니다. 즉, 항상 세션이 돌아가고, 항상 작업이 진행되고 있길 바라게 됩니다. 전부 노란색으로 변하면 얼른 새 작업을 하나 더 보내게 됩니다. 솔직히 말하면 Claude Code를 1분도 쉬지 않게 최대한 활용하는 것입니다.

사용량 패널

Claude Code Usage는 완전한 토큰 사용량 통계를 제공합니다. 상단에는 개요 표가 있습니다: 오늘, 이번 주, 이번 달에 각각 얼마나 많은 토큰을 사용했는지, 몇 개의 세션을 실행했는지.

아래에는 일일 사용량 추이 그래프(최근 7일), 모델별 소비 분류(Opus vs Sonnet vs Haiku), 프로젝트별 사용량 순위가 있습니다 — 드디어 어떤 프로젝트가 토큰을 가장 많이 소비하는지 볼 수 있게 됐습니다.

이제 가끔 이 패널을 확인하면서 각 프로젝트의 토큰 소비 상황을 파악합니다. 특정 프로젝트의 사용량이 비정상적으로 높으면, 전략을 적시에 조정할 수 있습니다. 예를 들어 일부 간단한 작업을 Opus에서 Sonnet으로 전환하는 식으로요.

확장 관리

Claude Code Extensions는 Plugins, Skills, MCP Servers 세 가지 차원을 하나의 인터페이스에 통합합니다.

Plugins 페이지는 설치된 모든 플러그인을 나열하고, 활성화/비활성화 상태, 버전 번호, 소스 저장소를 표시합니다. 원클릭으로 활성화, 비활성화, 업데이트, 제거가 가능하며, 각 플러그인에 포함된 commands, skills, agents, MCP servers도 확인할 수 있습니다.

MCP Servers 페이지는 설정된 모든 MCP 서버와 연결 상태를 표시합니다 — Connected(연결됨), Needs Auth(인증 필요), Unreachable(연결 불가). 인증이 필요한 서버의 경우, 인증 링크를 바로 열어서 권한 부여를 완료할 수 있습니다.

더 이상 "이 MCP가 도대체 연결된 건지 아닌지" 추측할 필요가 없습니다.

에피소드: 계정이 정지당하다

개발 과정에서 해프닝이 하나 있었습니다.

확장에는 각 세션에 자동으로 태그를 생성하는 기능이 있는데, Raycast에 내장된 AI 기능을 사용합니다. 디버깅 중에 여러 Claude Code 세션을 동시에 열어놓고 반복 테스트하다 보니, 세션이 시작될 때마다 Raycast AI를 호출하여 태그를 생성했고, 짧은 시간에 요청량이 급격히 올라갔습니다.

그러더니 어느 날 Raycast를 열었는데, 로그인이 안 됐습니다. 이메일 로그인도 안 되고, GitHub 로그인도 안 됐습니다.

받은 정지 통보 내용은 무시무시했습니다: 영구 정지, 서비스 약관 IV, VI, VIII조 위반, "AI 남용", 복구 불가.

멘붕이었습니다. 200달러짜리 Claude 크레딧도 다 쓸 시간이 없는데, 뭘 남용한다는 건지?

급히 Raycast의 Slack 커뮤니티에 이의를 제기했습니다. GitHub 저장소 링크를 첨부하면서, 코드를 확인해달라고 했습니다. 이건 정상적인 Claude Code 모니터링 플러그인이고, AI 호출은 플러그인 기능의 일부이지 남용이 아니라고 설명했습니다.

마침 주말이라 Raycast 팀이 출근하지 않았습니다. 이틀을 기다리고, 월요일에 Tirta가 답변했습니다. 다행히 태도가 좋았고, 바로 사과했습니다. 자동 감지 시스템이 플러그인의 정상적인 고빈도 AI 호출을 남용으로 오판한 것이었고, 이런 확장 기반의 호출 패턴은 이전에 고려하지 못했다며 자신들의 실수라고 했습니다. 계정은 즉시 복구됐습니다.

허탕을 치긴 했지만, 다른 관점에서 보면 이 플러그인이 정말 열심히 일하고 있었다는 증거이기도 합니다. 너무 부지런해서 플랫폼까지 당황하게 만든 셈입니다.

마치며

처음의 한 가지 생각 — "모든 세션 상태를 볼 수 있으면 좋겠는데" — 에서 지금의 Claude Code Monitor까지, 핵심 기능은 하룻밤이면 완성됐습니다. 이것이 AI 보조 개발의 실제 경험입니다: 세션 모니터링, 사용량 통계, 확장 관리, 메뉴바 상주를 포함한 완전한 도구가 아이디어에서 사용 가능한 상태까지, 예상보다 빠르게 만들어졌습니다.

이것이 AI 시대가 일반 개발자에게 주는 선물입니다: 생산성의 한계는 더 이상 어떤 기술 스택을 아느냐가 아니라, 어떤 문제를 해결하고 싶은가에 의해 결정됩니다.

프로젝트는 오픈소스이며, MIT 라이선스입니다. 사용과 기여를 환영합니다:

GitHub: wuyuxiangX/claude-code-monitor

Claude Code를 많이 사용하신다면, 한번 써보세요. 완벽히 맞지 않는다면 — 괜찮습니다, 직접 만들어보세요. 이제 그 능력이 있으니까요.