Claude Code Monitor: 멀티 세션 모니터링 시스템 완전 가이드
개요
Claude Code Monitor는 여러 개의 Claude Code 세션을 동시에 실시간으로 모니터링할 수 있는 혁신적인 CLI 도구입니다. 이 도구는 개발자들이 다양한 프로젝트나 작업을 병렬로 진행할 때 각 세션의 상태를 한눈에 파악하고 관리할 수 있도록 설계되었습니다. macOS 전용으로 개발된 이 도구는 파일 기반 상태 관리 시스템을 채택하여 별도의 API 서버 없이도 효율적으로 작동합니다.
프로젝트 배경과 의의
현대의 AI 기반 개발 환경에서 개발자들은 종종 여러 개의 Claude Code 세션을 동시에 실행하게 됩니다. 한 세션에서는 백엔드 API를 개발하고, 다른 세션에서는 프론트엔드 컴포넌트를 작업하며, 또 다른 세션에서는 테스트 코드를 작성하는 식입니다. 이처럼 복잡한 멀티태스킹 환경에서는 각 세션이 어떤 상태인지, 어떤 작업을 진행 중인지 추적하기 어려운 문제가 발생합니다.
Claude Code Monitor는 바로 이러한 문제를 해결하기 위해 탄생했습니다. 개발자는 이 도구를 통해 모든 Claude Code 세션의 상태를 실시간으로 확인할 수 있으며, 필요한 세션으로 즉시 전환할 수 있는 기능까지 제공받습니다. 이는 개발 워크플로우의 효율성을 크게 향상시키고, 컨텍스트 스위칭에 따른 인지적 부담을 줄여줍니다.
핵심 기술 특징
1. 서버리스 아키텍처
Claude Code Monitor의 가장 혁신적인 특징 중 하나는 서버리스 아키텍처입니다. 일반적인 모니터링 도구들이 별도의 API 서버를 필요로 하는 것과 달리, 이 도구는 파일 기반 상태 관리 시스템을 채택했습니다. 모든 세션 정보는 ~/.claude-monitor/sessions.json 파일에 저장되며, 이 파일의 변경사항을 실시간으로 감지하여 UI를 업데이트합니다.
이러한 접근 방식은 몇 가지 중요한 장점을 제공합니다. 첫째, 별도의 서버 프로세스를 실행할 필요가 없어 시스템 리소스를 절약할 수 있습니다. 둘째, 네트워크 통신이 필요 없어 보안성이 향상되고 레이턴시가 최소화됩니다. 셋째, 설치와 설정이 단순해져 사용자 경험이 크게 개선됩니다.
2. 실시간 모니터링 시스템
실시간 모니터링은 Claude Code Monitor의 핵심 기능입니다. 도구는 파일 시스템 감시(file watching) 기술을 활용하여 세션 상태 파일의 변경을 즉각적으로 감지합니다. Claude Code가 작업을 시작하거나, 사용자 입력을 대기하거나, 작업을 완료할 때마다 상태 파일이 업데이트되며, 이는 즉시 모니터 UI에 반영됩니다.
모니터링 UI는 세 가지 주요 상태를 시각적으로 구분하여 표시합니다. “Running” 상태는 실심볼(●)로 표시되며, Claude Code가 적극적으로 코드를 작성하거나 분석하는 중임을 나타냅니다. “Waiting” 상태는 반원 심볼(◐)로 표시되며, 사용자의 입력이나 권한 승인을 기다리는 상태를 의미합니다. “Done” 상태는 체크마크(✓)로 표시되며, 세션이 정상적으로 종료되었음을 나타냅니다.
3. 터미널 포커스 자동 전환
Claude Code Monitor의 가장 독특하고 실용적인 기능 중 하나는 터미널 포커스 자동 전환 기능입니다. 이 기능은 macOS의 AppleScript를 활용하여 구현되었으며, 사용자가 모니터 UI에서 특정 세션을 선택하면 해당 세션이 실행 중인 터미널 윈도우나 탭으로 자동으로 전환됩니다.
이 기능의 구현은 TTY(Teletypewriter) 경로 기반 타겟팅을 통해 이루어집니다. 각 터미널 세션은 고유한 TTY 경로(예: /dev/ttys001)를 가지며, 이를 통해 정확한 윈도우와 탭을 식별할 수 있습니다. iTerm2와 Terminal.app은 완전한 지원을 받으며, Ghostty는 애플리케이션 활성화는 가능하지만 특정 윈도우나 탭을 타겟팅하는 것은 제한적입니다.
4. 훅 시스템 통합
Claude Code Monitor는 Claude Code의 훅(hook) 시스템과 긴밀하게 통합되어 있습니다. 훅 시스템은 Claude Code의 다양한 생명주기 이벤트(세션 시작, 상태 변경, 세션 종료 등)에 대응하여 자동으로 실행되는 스크립트들의 집합입니다.
도구의 초기 설정 과정에서 ~/.claude/settings.json 파일에 필요한 훅 설정이 자동으로 추가됩니다. 이를 통해 Claude Code가 실행될 때마다 자동으로 세션 정보가 모니터링 시스템에 전달되며, 사용자는 별도의 수동 조작 없이 모든 세션을 추적할 수 있습니다.
주요 기능 상세 분석
대시보드 인터페이스
모니터의 대시보드 인터페이스는 심플하면서도 정보력 있는 디자인을 지향합니다. 화면은 활성 세션들의 목록으로 구성되며, 각 세션은 번호, 상태 아이콘, 작업 디렉토리 경로로 표시됩니다. 이러한 미니멀한 접근 방식은 사용자가 핵심 정보에 집중할 수 있도록 하며, 불필요한 시각적 노이즈를 제거합니다.
인터페이스는 키보드 중심의 탐색을 지원합니다. 사용자는 화살표 키나 vim 스타일의 j/k 키를 사용하여 세션 목록을 탐색할 수 있으며, Enter 키나 ‘f’ 키를 눌러 선택한 세션으로 포커스를 전환할 수 있습니다. 또한 1부터 9까지의 숫자 키를 사용하면 해당 번호의 세션으로 즉시 전환할 수 있어, 빠른 접근이 필요한 상황에서 유용합니다.
토큰 사용량 추적
이미지에서 확인할 수 있듯이, Claude Code Monitor는 각 세션의 토큰 사용량을 실시간으로 추적하는 대시보드 기능도 제공합니다. 대시보드는 다음과 같은 정보를 표시합니다:
- IN(read): 입력으로 읽어들인 토큰 수 (예: 75K)
- CACHE: 캐시된 토큰 수 (예: 231.0M)
- OUTPUT: 출력으로 생성된 토큰 수 (예: 369K)
- TOTAL: 총 토큰 비용 (예: £31.5M)
- IN(read)/OUT: 입출력 비율 (예: 0.2)
이러한 토큰 사용량 정보는 API 비용을 관리하고 최적화하는 데 매우 중요합니다. 특히 여러 세션을 동시에 운영하는 환경에서는 각 세션의 토큰 소비량을 실시간으로 모니터링하여 예산을 효과적으로 관리할 수 있습니다. 캐시 기능의 효율성도 확인할 수 있어, 프롬프트 최적화와 컨텍스트 관리 전략을 수립하는 데 도움이 됩니다.
세션 데이터 관리
세션 데이터는 체계적이고 효율적으로 관리됩니다. 각 세션은 다음과 같은 정보를 포함합니다:
- session_id: Claude Code 세션의 고유 식별자
- cwd: 작업 디렉토리의 전체 경로
- tty: 터미널 디바이스 경로 (예:
/dev/ttys001) - status: 현재 세션 상태 (running/waiting_input/stopped)
- updated_at: 마지막 업데이트 시간 타임스탬프
데이터의 수명 주기 관리도 자동화되어 있습니다. 30분 이상 활동이 없는 세션은 자동으로 제거되며, 터미널 세션이 종료되면 즉시 데이터가 정리됩니다. 이를 통해 스토리지 공간을 효율적으로 사용하고 UI를 깔끔하게 유지할 수 있습니다.
설치 및 설정
설치 방법
Claude Code Monitor는 두 가지 방식으로 설치할 수 있습니다. 권장되는 방법은 npm을 통한 글로벌 설치입니다:
1
npm install -g claude-code-monitor
글로벌 설치를 하면 ccm이라는 짧은 명령어를 시스템 어디에서든 사용할 수 있습니다. 이는 반복적으로 도구를 실행해야 하는 사용 패턴을 고려할 때 매우 편리합니다.
대안으로 npx를 사용하여 설치 없이 실행할 수도 있습니다:
1
npx claude-code-monitor
다만 이 방식은 매번 전체 패키지 이름을 입력해야 하므로, 지속적으로 사용하는 경우에는 글로벌 설치가 더 효율적입니다.
초기 설정
설치 후 처음 실행하면 자동으로 초기 설정이 진행됩니다. 사용자가 해야 할 일은 단순히 ccm 명령을 실행하는 것뿐입니다:
1
ccm
이 명령은 필요한 훅 설정이 존재하지 않으면 자동으로 설정 프로세스를 시작합니다. 훅 설정은 ~/.claude/settings.json 파일에 추가되며, 이를 통해 Claude Code가 모니터링 시스템과 통신할 수 있게 됩니다.
설정이 완료되면 Claude Code를 재시작해야 훅이 활성화됩니다. 이후부터는 모든 Claude Code 세션이 자동으로 모니터링 시스템에 등록됩니다.
설정 확인 및 문제 해결
설정이 올바르게 되었는지 확인하려면 다음 명령을 실행할 수 있습니다:
1
cat ~/.claude/settings.json | grep ccm
이 명령은 설정 파일에서 Claude Code Monitor와 관련된 설정을 찾아 표시합니다. 만약 아무것도 표시되지 않는다면 설정이 제대로 적용되지 않은 것이므로, ccm setup 명령을 다시 실행해야 합니다.
세션이 표시되지 않는 경우, 먼저 Claude Code를 재시작해보고, 그래도 해결되지 않으면 설정을 다시 확인해야 합니다. 포커스 기능이 작동하지 않는 경우, macOS의 시스템 환경설정에서 해당 터미널 애플리케이션에 접근성 권한이 부여되었는지 확인해야 합니다.
사용 가이드
기본 사용법
Claude Code Monitor의 기본 사용법은 매우 직관적입니다. 터미널에서 ccm 또는 ccm watch 명령을 실행하면 모니터 인터페이스가 나타납니다. 이 인터페이스는 현재 실행 중인 모든 Claude Code 세션을 실시간으로 표시합니다.
모니터가 실행 중일 때 새로운 Claude Code 세션을 시작하면, 자동으로 목록에 추가됩니다. 세션의 상태가 변경될 때마다 (예: 작업 중에서 입력 대기 상태로) UI가 즉시 업데이트되어 최신 정보를 제공합니다.
키보드 네비게이션
모니터 인터페이스는 다양한 키보드 단축키를 지원하여 효율적인 탐색을 가능하게 합니다:
- ↑/k: 목록에서 위로 이동
- ↓/j: 목록에서 아래로 이동
- Enter/f: 선택한 세션으로 포커스 전환
- 1-9: 해당 번호의 세션으로 즉시 전환
- c: 모든 세션 데이터 삭제
- q/Esc: 모니터 종료
이러한 키 바인딩은 vim 스타일의 키보드 탐색에 익숙한 개발자들을 고려하여 설계되었으며, 마우스 없이도 모든 기능을 효율적으로 사용할 수 있도록 합니다.
명령어 레퍼런스
Claude Code Monitor는 다양한 명령어를 제공하여 여러 상황에 대응할 수 있습니다:
ccm 또는 ccm watch (별칭: ccm w): 모니터 TUI를 실행합니다. 훅이 설정되지 않았다면 자동으로 설정 프로세스를 시작합니다.
ccm setup: Claude Code 훅을 수동으로 설정합니다. 설정에 문제가 있거나 재설정이 필요한 경우 사용합니다.
ccm list (별칭: ccm ls): 현재 등록된 모든 세션의 목록을 간단히 출력합니다. TUI가 아닌 텍스트 형태로 정보를 확인하고 싶을 때 유용합니다.
ccm clear: 모든 세션 데이터를 삭제합니다. 오래된 데이터를 정리하거나 문제 해결을 위해 깨끗한 상태에서 시작하고 싶을 때 사용합니다.
ccm –version (별칭: ccm -V): 현재 설치된 도구의 버전을 표시합니다.
ccm –help (별칭: ccm -h): 사용 가능한 모든 명령어와 옵션에 대한 도움말을 표시합니다.
고급 활용 방법
프로그래매틱 사용
Claude Code Monitor는 CLI 도구로서의 기능뿐만 아니라, Node.js 라이브러리로서도 사용할 수 있습니다. 이를 통해 다른 도구나 스크립트와 통합하여 더욱 강력한 워크플로우를 구축할 수 있습니다:
1
2
3
4
5
6
7
import { getSessions, getStatusDisplay } from 'claude-code-monitor';
const sessions = getSessions();
for (const session of sessions) {
const { symbol, label } = getStatusDisplay(session.status);
console.log(`${symbol} ${label}: ${session.cwd}`);
}
이러한 프로그래매틱 접근은 다양한 자동화 시나리오에 활용될 수 있습니다. 예를 들어, CI/CD 파이프라인에서 Claude Code 세션의 상태를 모니터링하거나, 커스텀 대시보드를 구축하거나, 알림 시스템과 통합하는 등의 활용이 가능합니다.
터미널 호환성
Claude Code Monitor는 macOS의 주요 터미널 애플리케이션들과 호환됩니다:
- iTerm2: 완전한 지원. TTY 기반 윈도우/탭 타겟팅이 정확하게 작동합니다.
- Terminal.app: 완전한 지원. Apple의 기본 터미널에서도 모든 기능이 원활하게 작동합니다.
- Ghostty: 제한적 지원. 애플리케이션 활성화는 가능하지만 특정 윈도우나 탭을 타겟팅할 수는 없습니다.
Alacritty, kitty, Warp 등의 다른 터미널들에서도 모니터링 기능 자체는 사용할 수 있지만, 포커스 전환 기능은 지원되지 않습니다. 이는 각 터미널의 스크립팅 API 지원 여부에 따라 결정됩니다.
데이터 관리 및 유지보수
세션 데이터를 효과적으로 관리하는 것은 도구의 성능과 안정성을 유지하는 데 중요합니다. 데이터 파일의 위치는 ~/.claude-monitor/sessions.json이며, 이 파일은 JSON 형식으로 구조화되어 있어 필요시 수동으로 편집할 수도 있습니다.
데이터가 손상되었거나 문제가 발생한 경우, 간단히 파일을 삭제하여 초기 상태로 되돌릴 수 있습니다:
1
rm ~/.claude-monitor/sessions.json
또는 ccm clear 명령을 사용하여 안전하게 데이터를 정리할 수 있습니다. 이 명령은 단순히 파일을 삭제하는 것이 아니라 적절한 클린업 프로세스를 거쳐 데이터를 제거합니다.
실제 사용 시나리오
시나리오 1: 풀스택 개발
프론트엔드와 백엔드를 동시에 개발하는 풀스택 개발자의 경우, 한 Claude Code 세션에서는 React 컴포넌트를 작성하고, 다른 세션에서는 API 엔드포인트를 개발하며, 또 다른 세션에서는 데이터베이스 마이그레이션을 관리할 수 있습니다. Claude Code Monitor를 사용하면 각 세션의 진행 상황을 한눈에 파악하고, 필요할 때 즉시 해당 세션으로 전환할 수 있습니다.
시나리오 2: 멀티 프로젝트 관리
여러 클라이언트 프로젝트를 동시에 진행하는 프리랜서 개발자나 컨설턴트의 경우, 각 프로젝트마다 별도의 Claude Code 세션을 유지할 수 있습니다. 모니터는 각 프로젝트의 디렉토리 경로를 표시하므로, 어떤 세션이 어떤 프로젝트에 해당하는지 쉽게 식별할 수 있습니다.
시나리오 3: 코드 리뷰 및 리팩토링
대규모 코드베이스에서 여러 모듈을 동시에 리팩토링하거나 리뷰하는 경우, 각 모듈마다 별도의 Claude Code 세션을 열어 작업할 수 있습니다. 한 세션에서 UI 컴포넌트를 리팩토링하는 동안, 다른 세션에서는 비즈니스 로직을 검토하고, 또 다른 세션에서는 테스트를 업데이트할 수 있습니다.
시나리오 4: 학습 및 실험
새로운 기술이나 라이브러리를 학습하면서 여러 예제를 동시에 실험하는 경우, 각 실험마다 독립적인 세션을 유지하면서 결과를 비교할 수 있습니다. 모니터를 통해 각 실험의 진행 상태를 추적하고, 흥미로운 결과가 나온 세션으로 신속하게 전환할 수 있습니다.
보안 및 프라이버시
Claude Code Monitor는 사용자의 보안과 프라이버시를 최우선으로 고려하여 설계되었습니다. 모든 데이터는 로컬 파일 시스템에 저장되며, 어떠한 네트워크 요청도 수행하지 않습니다. 이는 민감한 프로젝트 정보나 코드가 외부로 유출될 위험이 없음을 의미합니다.
도구가 수정하는 유일한 시스템 파일은 ~/.claude/settings.json으로, 이는 Claude Code의 공식 설정 파일입니다. 훅 설정은 Claude Code의 표준 메커니즘을 사용하므로, 시스템의 다른 부분에 영향을 미치지 않습니다.
포커스 기능에 사용되는 AppleScript는 터미널 애플리케이션 제어에만 제한되어 있으며, 다른 시스템 기능에는 접근하지 않습니다. 다만 이 기능을 사용하기 위해서는 macOS의 접근성 권한이 필요하므로, 사용자는 시스템 환경설정에서 적절한 권한을 부여해야 합니다.
실용적인 물리적 구현
이미지에서 보여지는 하드웨어 디스플레이는 Claude Code Monitor의 개념을 물리적 형태로 구현한 흥미로운 사례입니다. 작은 LCD 디스플레이 장치들(아마도 Raspberry Pi나 유사한 마이크로컴퓨터 기반)이 실시간으로 Claude Code 세션의 상태를 표시하고 있습니다.
이러한 물리적 구현은 몇 가지 장점을 제공합니다. 첫째, 개발자가 코딩에 집중하면서도 주변 시야로 세션 상태를 확인할 수 있어 집중력을 해치지 않습니다. 둘째, 여러 모니터를 사용하는 환경에서 별도의 화면 공간을 할애할 필요 없이 독립적인 디스플레이로 정보를 제공합니다. 셋째, 팀 환경에서 다른 팀원들도 현재 진행 중인 작업의 상태를 한눈에 파악할 수 있습니다.
특히 토큰 사용량 대시보드 기능은 실시간 비용 모니터링을 가능하게 하여, 개발자가 API 비용을 효과적으로 관리할 수 있도록 돕습니다. 이는 특히 대규모 프로젝트나 여러 세션을 동시에 운영하는 환경에서 매우 유용합니다.
커뮤니티와 에코시스템
Claude Code Monitor는 오픈소스 프로젝트로, MIT 라이선스 하에 공개되어 있습니다. 이는 누구나 자유롭게 사용하고, 수정하고, 배포할 수 있음을 의미합니다. GitHub 저장소에는 이미 6개의 스타와 1개의 포크가 있으며, 커뮤니티의 관심이 점차 증가하고 있습니다.
프로젝트는 TypeScript로 작성되어 있으며(93.5%), 현대적인 개발 도구와 실천방법을 따르고 있습니다. 코드 품질 관리를 위해 Biome를 사용하고, 테스트를 위해 Vitest를 활용하며, 지속적 통합을 위해 GitHub Actions를 구성하고 있습니다.
개발자들은 GitHub Issues를 통해 버그를 보고하거나 새로운 기능을 제안할 수 있으며, Pull Request를 통해 직접 기여할 수도 있습니다. 프로젝트의 CHANGELOG.md 파일은 각 버전의 변경사항을 투명하게 기록하고 있어, 사용자들이 최신 기능과 수정사항을 쉽게 파악할 수 있습니다.
미래 전망과 발전 방향
Claude Code Monitor는 현재도 강력한 도구이지만, 앞으로 더욱 발전할 수 있는 여러 가능성이 있습니다. 예를 들어, 크로스 플랫폼 지원을 추가하여 Linux와 Windows 사용자들도 혜택을 받을 수 있도록 할 수 있습니다. 비록 포커스 전환 기능은 각 OS의 고유한 API에 의존하지만, 핵심 모니터링 기능은 충분히 이식 가능합니다.
또한 더 많은 터미널 애플리케이션에 대한 지원을 추가할 수 있습니다. 현재 Alacritty, kitty, Warp 등의 인기 있는 터미널들은 포커스 기능을 지원하지 않지만, 이들 터미널의 개발이 진행됨에 따라 필요한 API가 추가될 수 있습니다.
더 풍부한 통계 및 분석 기능도 추가될 수 있습니다. 예를 들어, 시간대별 토큰 사용량 그래프, 세션별 평균 응답 시간, 가장 활발하게 사용된 프로젝트 디렉토리 등의 인사이트를 제공할 수 있습니다. 이러한 데이터는 개발 패턴을 이해하고 워크플로우를 최적화하는 데 도움이 될 것입니다.
클라우드 동기화 기능도 고려해볼 만합니다. 여러 컴퓨터에서 작업하는 개발자들이 자신의 세션 기록과 설정을 동기화할 수 있다면 유용할 것입니다. 물론 이는 보안과 프라이버시에 대한 신중한 고려가 필요합니다.
결론
Claude Code Monitor는 AI 기반 개발 환경에서 필수적인 도구로 자리잡을 잠재력을 가지고 있습니다. 멀티 세션 모니터링이라는 명확한 목적을 가지고 설계되었으며, 그 목적을 효과적이고 우아하게 달성합니다. 서버리스 아키텍처, 실시간 업데이트, 터미널 포커스 전환 등의 기능들은 개발자의 생산성을 크게 향상시킵니다.
도구의 설계 철학은 단순성과 실용성을 중시합니다. 불필요한 기능으로 복잡도를 높이기보다는, 핵심 기능을 완벽하게 구현하는 데 집중했습니다. 이러한 접근은 Unix 철학의 “한 가지 일을 잘하는 작은 도구들”이라는 원칙과 일맥상통합니다.
오픈소스 프로젝트로서 커뮤니티의 참여와 기여를 환영하며, 지속적으로 개선되고 발전할 것입니다. 이미지에서 보여지는 물리적 구현 사례는 이 도구가 단순한 CLI 도구를 넘어 창의적으로 활용될 수 있음을 보여줍니다.
Claude Code를 사용하는 모든 개발자, 특히 여러 프로젝트를 동시에 관리하거나 복잡한 워크플로우를 다루는 개발자들에게 Claude Code Monitor는 필수적인 도구가 될 것입니다. 간단한 설치와 직관적인 사용법, 강력한 기능의 조합은 이 도구를 현대 개발 툴킷의 중요한 부분으로 만듭니다.
작성 일자: 2026-01-25