Claude Code 멀티 에이전트 팀을 위한 실시간 Observability 대시보드

Who Should Read

Claude Code를 여러 에이전트로 병렬 실행하거나 복잡한 멀티에이전트 워크플로를 운영 중인 개발자. 에이전트가 실패했을 때 사후 로그 분석 말고 실시간으로 무슨 일이 벌어지는지 파악하고 싶은 상황에 딱 맞다.

Core Mechanics

• Claude Code가 자율적으로 서브에이전트를 스폰하고 툴을 호출할 때, 터미널에서는 전체 활동의 일부밖에 보이지 않는다. 서브에이전트들은 사실상 '보이지 않는' 상태로 동작하고, 뭔가 3단계 깊이에서 잘못됐을 때는 사후에 로그를 뒤지는 수밖에 없었는데, 이 프로젝트가 그 문제를 해결한다.
• OTEL(OpenTelemetry, 분산 추적 표준 프레임워크) 대신 Claude Code의 훅(hook) 시스템을 사용해 이벤트를 캡처한다. 훅을 쓰면 에이전트 동작의 전체 그림을 잡을 수 있고, 툴 호출 순서와 내용을 그대로 기록할 수 있다.
• 설치 방법이 간단하다. `claude plugin marketplace add simple10/agents-observe` → `claude plugin install agents-observe` → Claude Code 재시작 순서로 하면 다음 세션부터 Docker 컨테이너가 자동으로 뜨고 http://localhost:4981 에서 대시보드를 볼 수 있다. Docker와 Node.js가 사전 요구사항이다.
• 훅의 성능 영향을 최소화하기 위해 블로킹(동기) 방식 대신 백그라운드 비동기 방식으로 구현했다. 에이전트가 분당 수십 번 툴 호출을 하는 환경에서 훅 하나당 100ms만 블로킹해도 태스크 전체에 2~3초가 추가되고, 병렬 에이전트가 많을수록 이게 곱으로 불어난다.
• 로컬과 리모트 모두 지원한다. 서버와 대시보드를 원격 VM에서 돌리면 여러 Claude Code 인스턴스가 같은 서버에 이벤트를 보낼 수 있고, 멀티 에이전트 팀 전체를 한 곳에서 모니터링할 수 있다.
• 대시보드에는 강력한 필터링, 검색, 멀티에이전트 세션 시각화 기능이 포함된다. 에이전트가 어떤 순서로 어떤 툴을 호출했는지 타임라인 형태로 확인할 수 있어서, '에이전트가 어떻게 이 결론에 도달했는지'를 사후에 재구성할 수 있다.
• /observe, /observe status 두 가지 슬래시 커맨드를 제공해서 Claude Code 세션 안에서 바로 대시보드 URL을 열거나 서버 상태를 확인할 수 있다.
• OpenClaw(다른 멀티에이전트 프레임워크) 지원도 로드맵에 있다. 훅 아키텍처가 세션 이벤트를 동일한 파이프라인에 흘려보낼 수 있는 구조라서 다른 에이전트 런타임으로 확장이 가능하다.

Evidence

• 병렬로 여러 Claude Code 에이전트를 원격 VM에서 운영하는 사용자가 '훅이 에이전트 크리티컬 패스에서 블로킹되면 처리량이 급격히 떨어진다'는 걸 직접 경험했다고 공유했다. 에이전트가 분당 수십 번 툴 호출을 하는데 훅마다 수백 ms가 쌓이면 체감이 크다는 것. Docker 기반 서비스 패턴이 에이전트 자체에 오버헤드를 안 주면서 관찰성을 확보하는 올바른 트레이드오프라고 평가했다.
• 멀티에이전트 운영에서 '에이전트의 자기 보고가 실제 결과와 일치하는지 알 수 없다'는 투명성 문제를 지적하는 의견이 여러 명에게서 나왔다. 코디네이터가 builder, reviewer, tester 에이전트를 병렬로 스폰할 때, 각 에이전트가 보고하는 결과는 '위생 처리된 낙관론(sanitised optimism)'일 수 있고 이벤트 스트림 로그가 실제로 결과가 맞는지까지는 검증해주지 못한다는 한계도 언급됐다.
• 여러 에이전트 팀이 동일한 JSONL 파일에 동시에 쓸 때의 동시성 처리 문제가 질문으로 제기됐다. 병렬 에이전트 환경에서 로그 파일 충돌 처리가 어떻게 되는지 구체적인 답변은 스레드에서 확인되지 않았다.
• Claude Code 사용량 비용에 대한 놀람 반응도 있었다. 'Claude 토큰에 하루 수백~수천 달러를 쓰냐'는 댓글이 달렸는데, 여러 에이전트를 장시간 병렬 운영하는 헤비 유저들이 이 도구의 주요 타깃임을 시사한다. 일반 개발자는 사용량 제한에 금방 걸린다는 현실적인 코멘트도 있었다.
• 서브에이전트가 자신의 서브에이전트를 또 스폰하는 경우(트리 구조)에서 대시보드가 전체 트리를 추적하는지 한 레벨만 추적하는지 묻는 질문이 있었다. 이는 실제 운영 환경에서 중요한 엣지 케이스인데, 해당 스레드에서 명확한 답변은 확인되지 않았다.

How to Apply

• Claude Code로 여러 에이전트를 병렬 실행하는데 뭔가 잘못됐을 때 원인 파악이 어렵다면, `claude plugin install agents-observe`로 설치하고 localhost:4981 대시보드에서 실시간으로 툴 호출 흐름을 모니터링하면 사후 로그 분석 없이 문제 지점을 바로 파악할 수 있다.
• 원격 VM에서 Claude Code 에이전트 팀을 운영 중이라면 Docker Compose로 서버를 올리고 여러 인스턴스가 같은 엔드포인트로 이벤트를 보내게 설정하면 분산된 에이전트들을 단일 대시보드에서 관찰할 수 있다. `docker-compose.yml`이 이미 포함되어 있다.
• 에이전트가 내놓는 결과물의 신뢰성이 의심스러운 경우, 이벤트 타임라인을 통해 에이전트가 어떤 파일을 읽고 어떤 커맨드를 실행했는지 실제 경로를 역추적하면 '자기 보고'와 실제 동작의 괴리를 발견할 수 있다.
• 훅 기반 자체 모니터링 시스템을 직접 구현하려다가 성능 문제로 포기했다면, 이 프로젝트의 백그라운드 비동기 훅 패턴을 참고해서 에이전트 크리티컬 패스를 블로킹하지 않는 구조로 개선할 수 있다.

Code Example

# 설치 방법
claude plugin marketplace add simple10/agents-observe
claude plugin install agents-observe
# Claude Code 재시작 후 자동으로 Docker 컨테이너 시작
# 대시보드: http://localhost:4981

# Claude Code 세션 내에서 사용 가능한 슬래시 커맨드
/observe          # 대시보드 URL 열기 + 서버 실행 상태 확인
/observe status   # 서버 헬스 체크 및 URL 표시

# Docker Compose로 직접 실행
docker-compose up -d

Terminology

Related Resources

• https://github.com/simple10/agents-observe
• https://github.com/simple10/agents-observe/blob/main/AGENTS.md
• https://github.com/simple10/agents-observe/blob/main/CLAUDE.md
• https://github.com/simple10/agents-observe/blob/main/CONTRIBUTING.md