Claude Code Hooks 기반 실시간 이벤트 캡처로 다중 에이전트 디버깅 효율성 향상함

Show HN: Real-time dashboard for Claude Code agent teams

2026년 4월 1일7분intermediate

AI 요약

Context

Claude Code가 자율적으로 서브에이전트를 스폰하고 도구를 호출할 때 터미널은 활동의 일부만 보여줌. 병렬 실행 중 세 에이전트 깊이에서 문제가 발생하면 사후에 로그를 읽어야 하는 상황임.

Technical Solution

Claude Code Hooks: OTEL 대신 세션 전체 캡처를 위해 hooks 사용함
observe_cli.mjs: stdin에서 이벤트 읽고 프로젝트 이름 추가 후 API 서버로 POST하는 dumb pipe 역할임
WebSocket: 캡처된 이벤트를 구독된 클라이언트에 실시간 스트리밍함
SQLite: 에이전트 메타데이터와 이벤트 저장소로 사용함
React Dashboard: 이벤트 스트림에서 에이전트 상태, 이벤트 카운트, 타이밍 파생함

Impact

실시간으로 각 에이전트의 행동, 도구 호출, 파일 접근을 관찰 가능함. PreToolUse와 PostToolUse를 단일 행으로 병합하여 도구 이벤트 중복 제거함.

Key Takeaway

dumb pipe 아키텍처로 hook script와 대시보드의 책임을 분리하면 확장성과 유지보수성이 높아짐. 서버는 단순 저장소 역할만 수행하여 클라이언트에서 모든 상태를 파생함.

실천 포인트

Claude Code로 다중 에이전트 프로젝트 개발 시 agents-observe 플러그인을 설치하면 Docker 컨테이너 기반으로 서버가 자동 실행되고 localhost:4981에서 실시간 대시보드를 통해 에이전트 활동과 도구 호출 흐름을 모니터링할 수 있음. 이벤트 캡처가 안 될 경우 /observe status로 서버 상태 확인 후 docker logs agents-observe로 문제 진단이 가능함.

태그

#Docker #Claude_Code #WebSocket #Multi-agent #Observability

원문 읽기