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

TL;DR Highlight

오픈소스 실시간 모니터링 대시보드가 Claude Code의 병렬 서브에이전트 실행 시 터미널에서 보이지 않는 툴 호출, 서브에이전트 동작, 이벤트 흐름을 한 화면에서 추적한다.

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

snippet

# 설치 방법
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

HookClaude Code에서 특정 이벤트(툴 호출, 파일 읽기 등)가 발생할 때 자동으로 실행되는 스크립트. 에이전트 동작을 가로채서 로깅하거나 추가 처리를 할 수 있다.

OTELOpenTelemetry의 약자. 분산 시스템에서 로그, 메트릭, 트레이스를 수집하는 표준화된 관찰성 프레임워크. 이 프로젝트는 OTEL 대신 Claude 전용 훅을 써서 더 세밀한 이벤트를 캡처한다.

Subagent메인 에이전트(코디네이터)가 작업을 분담하기 위해 새로 생성하는 하위 에이전트. 각자 독립적으로 툴을 호출하고 작업을 수행하는데, 기본적으로 상위 에이전트에서는 이 동작이 보이지 않는다.

Observability시스템 내부에서 무슨 일이 일어나는지 외부에서 파악할 수 있는 능력. 블랙박스처럼 동작하는 에이전트를 '유리 박스'처럼 들여다볼 수 있게 만드는 것.

JSONLJSON Lines의 약자. 각 줄이 독립적인 JSON 객체인 텍스트 파일 형식. 로그나 이벤트 스트림을 줄 단위로 append하기에 적합하다.

Critical Path전체 작업 완료 시간에 직접 영향을 주는 처리 경로. 여기서 블로킹이 발생하면 다른 작업이 아무리 빨라도 전체가 느려진다.