에이전트 관찰: Claude 코드 에이전트 팀 모니터링을 위한 실시간 대시보드

Agents Observe의 기능

Agents Observe는 Claude Code 에이전트 팀을 위해 특별히 제작된 실시간 가시성 대시보드입니다. Claude Code가 자율적으로 실행될 때(서브에이전트 생성, 도구 호출, 파일 읽기, 명령 실행) 발생하는 가시성 격차를 해결하며, 모든 훅 이벤트를 실시간으로 캡처하여 라이브 대시보드로 스트리밍합니다.

주요 기능 및 아키텍처

이 도구는 OTEL(OpenTelemetry) 대신 Claude Code 훅을 사용하여 개발자가 "에이전트 동작의 전체 그림"이라고 설명하는 내용을 캡처합니다. 아키텍처는 다음과 같은 흐름을 따릅니다:

• Claude Code Hooks → observe_cli.mjs → API Server (SQLite) → React Dashboard
• 훅 스크립트는 stdin에서 원시 이벤트를 읽고 프로젝트 이름을 추가한 후 서버로 POST 요청을 보냅니다
• 서버는 이벤트를 파싱하고, 에이전트 메타데이터(이름, 유형, 부모 관계)를 저장하며, 이벤트를 WebSocket 클라이언트로 전달합니다
• React 대시보드는 이벤트 스트림에서 모든 에이전트 상태를 파생합니다

대시보드를 통해 다음을 할 수 있습니다:

• 도구 호출이 발생하는 대로 실시간으로 스트리밍되는 것을 관찰합니다(결과와 함께 PreToolUse → PostToolUse)
• 전체 에이전트 계층 구조 확인—어떤 부모 에이전트가 어떤 서브에이전트를 생성했는지
• 에이전트, 도구 유형별로 필터링하거나 모든 이벤트에서 검색
• 어떤 이벤트든 확장하여 전체 페이로드, 명령 및 결과 확인
• 타임라인 아이콘 클릭하여 스트림의 특정 이벤트로 이동
• 사람이 읽을 수 있는 이름(예: "twinkly-hugging-dragon")으로 과거 세션 탐색

설치 및 설정

필수 조건:

• Docker(필수—서버가 컨테이너로 실행됨)
• Node.js(필수—훅 스크립트가 node를 통해 실행됨)

플러그인 설치 단계:

claude plugin marketplace add simple10/agents-observe
claude plugin install agents-observe

Claude Code를 재시작한 후, 다음 세션에서 서버가 Docker 컨테이너로 자동 시작되며 훅이 이벤트 캡처를 시작합니다. 대시보드는 http://localhost:4981에서 사용할 수 있습니다.

플러그인 기능

• /observe — 대시보드 URL을 열고 서버가 실행 중인지 확인
• /observe status — 서버 상태 확인 및 대시보드 URL 표시

개발 과정에서 얻은 성능 인사이트

개발자는 도구를 구축하고 사용하면서 얻은 여러 기술적 학습 내용을 공유했습니다:

• Claude Code 훅은 블로킹 방식입니다—훅을 사용하는 많은 플러그인이 있으면 성능이 급격히 저하됩니다
• 훅은 OTEL 데이터보다 더 유용한 정보를 제공합니다
• Claude의 jsonl 파일은 전체 그림을 제공합니다
• 플러그인에 의해 시작된 MCP 프로세스의 라이프사이클 관리는 "최선의 경우에도 다소 투박합니다"
• 백그라운드(실행 후 잊어버림) 훅으로 전환하고 다른 플러그인을 제거하면 Claude 성능이 크게 향상되었습니다

개발자는 서버가 활성 연결을 추적하고 사용하지 않을 때 자동 종료한 후, 플러그인이 새 세션이 시작될 때 다시 시작하는 프로세스 관리 솔루션을 구현했습니다. 이 Docker 기반 접근 방식은 서비스를 격리함으로써 보안을 향상시킬 수 있는 패턴으로 언급되었습니다.