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

관련 논문

• ctx – 로컬 머신의 코딩 에이전트 히스토리를 검색하는 CLI 도구

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Model API 내부 협업으로 Frontier 모델을 이기는 방법 (vLLM Semantic Router)

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: 에이전틱 코딩을 위한 자기 개선형 오픈소스 모델

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Tool-Augmented Agent에서의 Entity Binding 실패 분석

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: 터미널에서 여러 AI Agent를 한 번에 관리하는 Agent Multiplexer

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: 스스로 Scaffold를 생성하는 Agentic Coding LLM

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

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