hoangsonww/Claude-Code-Agent-Monitor

🚀 A real-time monitoring dashboard for Claude Code & Codex, built with SQLite3, Node.js, Express, React, Vite, TailwindCSS, & WebSockets. It tracks sessions, agent activity, tool usage, and subagent orchestration, providing live analytics, a Kanban status board, status notifications, a cute buddy, & an interactive web UI/MacOS/Windows native app.

Claude Code & Codex Agent Dashboard

무엇인가요 – Anthropic의 Claude Code와 OpenAI의 Codex 에이전트의 실시간 활동을 모니터링하는 자체 호스팅 웹 애플리케이션입니다. 에이전트가 발생시키는 훅 이벤트(도구 호출, 서브에이전트 실행, 토큰 사용량, 오류 등)를 수신하여 로컬 SQLite 데이터베이스에 저장하고, WebSockets / Server-Sent Events를 통해 React 기반 UI로 데이터를 전송합니다. UI는 세션, 에이전트, 도구 사용량, 토큰 흐름, 헬스 메트릭, 워크플로 그래프를 시각화하며, 데스크톱 래퍼(Electron)와 VS Code 확장 프로그램을 제공하여 빠른 접근을 가능하게 합니다.

핵심 기능 (README에 설명됨)

실시간 모니터링 – 훅 핸들러가 Claude Code / Codex에서 오는 HTTP POST를 수신하고 SQLite에 기록한 후 즉시 업데이트를 브로드캐스트합니다.
풍부한 시각화 – 토큰 사용량을 위한 D3/Mermaid 차트, 도구 빈도 히트맵, 서브에이전트 오케스트레이션의 DAG, 도구 파이프라인의 샌키 다이어그램, 헬스 스코어 게이지.
칸반 보드 – 에이전트와 세션을 상태(작업 중, 대기 중, 완료, 오류 등)별로 그룹화하고, 마우스 오버 시 대기 이유를 설명하는 툴팁을 제공합니다.
세션 탐색기 – 모든 기록된 세션을 페이지네이션 및 검색 가능한 테이블로 표시하며, 비용, 모델, 지속 시간, 세션별 상세 페이지(에이전트, 대화 전사, 타임라인, 분석)를 제공합니다.
국제화 – i18next를 사용하여 영어, 중국어, 베트남어, 한국어, 스페인어를 지원하며, 리로드 후에도 언어 설정이 유지됩니다.
플러그인 마켓플레이스 및 확장 기능 – Claude Code / Codex 플러그인, 기술, 서브에이전트를 위한 내장 레이어로, 로컬 MCP(Model-Context-Protocol) 서버를 통해 대시보드와 상호작용할 수 있습니다.
데스크톱 및 IDE 통합 – macOS(DMG) 및 Windows(NSIS/포터블)용 Electron 빌드; VS Code 확장 프로그램을 통해 에디터에서 바로 대시보드를 열 수 있습니다.
관측성 스택 – 프로덕션 배포를 위한 옵션으로 Prometheus 메트릭, Grafana 대시보드, OpenTelemetry 컬렉터, Coralogix 통합 제공.
배포 유연성 – Docker/Podman 이미지, Helm 차트, Terraform 모듈, Kubernetes 매니페스트 제공; 서버는 단순한 npm start 프로세스로도 실행 가능.
자동화 도구 – CLI 스크립트, Make 타겟, GitHub Actions를 활용한 자동 릴리스 파이프라인(빌드, 테스트: Vitest + React Testing Library, 배포).

기술 스택 (README 배지 목록 요약)

계층	기술
백엔드	Node.js ≥ 22, Express 4.21, better-sqlite3 (WAL 모드), WebSocket, Server-Sent Events, Swagger-UI, OpenAPI 3, Multer (파일 업로드)
프론트엔드	React 19, TypeScript 5, Vite 7, Tailwind CSS, D3.js, Mermaid, i18next, React-Router
데스크톱	Electron 35 + electron-builder
관측성	Prometheus, Grafana, OpenTelemetry, Coralogix
인프라	Docker, Podman, OCI, Kubernetes ≥ 1.29, Helm, Terraform ≥ 1.7, Nginx ingress
테스트 / 린팅	Vitest, React Testing Library, ESLint, Prettier
데이터베이스	SQLite 3 (better-sqlite3를 통해)
CI/CD	GitHub Actions (자동 릴리스)
라이선스	MIT

누구에게 유용할까

Claude Code 또는 Codex를 사용해 멀티에이전트 애플리케이션을 개발하는 개발자 – 에이전트가 도구를 호출하고, 서브에이전트를 생성하며, 토큰을 소비하는 방식을 시각화하고 싶은 사람.
LLM 기반 코드 어시스턴트를 운영하는 팀 – 사용량, 비용, 오류 패턴을 감사할 수 있는 중앙 UI가 필요한 사람.
대규모로 LLM 에이전트를 배포하는 운영팀 / SRE – 대시보드 UI 외에도 Prometheus 메트릭과 Grafana 대시보드를 원하는 사람.
에이전트 오케스트레이션, 도구 사용 패턴, 세션 간 토큰 흐름을 연구하는 연구자.

시작하기 (README의 빠른 시작 안내)

리포지토리 클론

git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
cd Claude-Code-Agent-Monitor

의존성 설치

npm ci   # 백엔드 및 프론트엔드 패키지 설치

서버 실행 (개발 모드)

npm run dev   # Express + SQLite + WebSocket + 핫리로드 Vite UI 시작

Claude Code / Codex 설정
- 에이전트의 네이티브 훅 설정에 제공된 훅 URL(예: http://localhost:3000/hook)을 추가하여 도구 사용, 중지 등 시 이벤트를 POST하도록 설정.
대시보드 열기
- http://localhost:5173 (Vite 개발 서버)에 접속하거나 패키지된 Electron 앱을 실행.
옵션: 프로덕션 배포
- UI 빌드: npm run build
- 컴파일된 Express 서버 실행: npm start
- 또는 제공된 Dockerfile / Helm 차트를 사용해 컨테이너화/K8s 배포.

더 많은 정보 찾기

위키 – 실용적인 안내서, 자동화 레시피, 문제 해결: https://github.com/hoangsonww/Claude-Code-Agent-Monitor/wiki
Docs 폴더 – 상세한 API 사양, i18n 가이드, 서버 아키텍처, MCP 통합 설명.
로컬라이즈된 README – 중국어, 베트남어, 한국어, 스페인어 버전으로 지역별 팁 제공.