Claude Agent Orchestrator

A local dashboard that visualizes Claude Code agent activity in real-time. Pixel-art characters represent agent states and roam freely in the workspace. 🌐 UI supports both Korean and English.

Claude Code의 에이전트 활동을 실시간으로 시각화하는 로컬 대시보드입니다. 픽셀아트 캐릭터들이 에이전트의 상태를 표현하고, 워크스페이스에서 자율적으로 활동합니다.

💡 설치가 귀찮다면? 이 README를 Claude Code에게 보여주고 "설치해줘"라고 하면 됩니다.

https://github.com/user-attachments/assets/30cf8a5c-3e5a-4264-904e-31a7310a8cb2

주요 기능

• 실시간 에이전트 모니터링 — SSE 기반으로 에이전트 시작/완료/도구 사용을 실시간 추적
• 픽셀아트 캐릭터 — 에이전트별 고유 캐릭터가 워크스페이스에서 배회, 수면, 작업
• CLAUDE.md 편집 — 전역/프로젝트별 CLAUDE.md를 대시보드에서 직접 편집
• 에이전트 관리 — ~/.claude/agents/*.md 파일 생성/편집/삭제, 드래그앤드롭 순서 변경 (order 필드로 .md 파일에 저장)
• 프로젝트별 에이전트 토글 — 프로젝트마다 사용할 에이전트를 on/off 설정
• MCP 서버 목록 — 연결된 MCP 서버 현황 표시
• Hooks 현황 — 설정된 훅 핸들러 목록 표시
• 타임라인 — 에이전트 실행 시간 바 차트 (Master 진행 상태는 액티비티 패널에서 확인)
• 세션 관리 — 멀티 세션 탭, 이름 변경(더블클릭), 드래그앤드롭 순서 변경(브라우저에 저장), 상태 추적
• /rename 자동 동기화 — Claude Code에서 /rename 명령 실행 시 탭 이름 실시간 갱신
• 세션 히스토리 — 종료된 세션의 질문 프롬프트 원문 + 응답 요약 자동 저장, 에이전트/도구/파일 통계 포함 (7일·10MB·세션당 100질문 가드)
• 히스토리 검색 — 프롬프트/파일명/세션명 키워드 검색 + 날짜/에이전트 필터, 매칭 하이라이트
• 히스토리 사용 안 함 토글 — ON 시 이후 종료되는 세션은 디스크에 저장하지 않음 (메모리/실시간 UI는 계속 동작)
• 히스토리 삭제 — 모달 헤더의 "전체 삭제" 버튼 + 행 단위 ✕ 버튼 (inline 2단계 confirm)
• 민감정보 자동 마스킹 — sk-*, ghp_*, AKIA*, JWT, Bearer 토큰 등 자동 치환
• 브라우저 알림 — 탭 비활성 시 에이전트 완료, 응답 완료 알림 (on/off 토글)
• 일일 통계 — 오늘의 질문 수, 에이전트별/도구별 사용 횟수, 주간/누적 통계, 🔄 전체 초기화 지원
• 🌱 활동 잔디 — GitHub contribution graph 스타일. 년도별 1월~12월 전체 표시 + 년도 탭 전환. 데이터 무제한 보관
• 😄 캐릭터 감정 이모지 — working(💦🔥⚡), done(✨🎉❤️), ESC 중단(❗😵) 시 캐릭터 위에 팝업
• 💬 캐릭터 간 대화 — 2명 이상 동시 working 시 랜덤 대화 교환 ("도와줄까?" → "괜찮아 거의 끝나")
• ⏱️ 세션 타이머 — 헤더에 현재 세션 경과 시간 표시
• ⌨️ ESC 단축키 — 열려있는 모달을 ESC 키로 닫기

• 마을(우주) 모드 — 우주 배경 + 별/은하수/nebula/별똥별/별자리. 워크스페이스 폭에 따라 캐릭터 크기 자동 조정 (Tier 1/2/3). 항상 활성 (이전 환경 효과 토글은 제거됨)
• 💭 Thinking 말풍선 — Master가 생각 중일 때 구름 모양 말풍선 + ··· 바운스 애니메이션 (일반 작업 말풍선과 시각적 구분)
• 🖱️ 캐릭터 드래그 재배치 — 워크스페이스에서 캐릭터를 마우스/터치로 자유롭게 이동 (grab 커서, 글로우 효과, 안전 경계 clamp)
• 📐 계보선 — Master가 에이전트를 spawn하면 대시 연결선이 실시간으로 표시, 캐릭터 이동에 따라 15fps 업데이트
• 🏆 포인트 히스토리 & 성취 — 일별 포인트 획득/사용 추이 + 성취 배지 (마스터/에이전트/수집/이벤트 카테고리). 🏆 버튼으로 모달 열기

• 🎮 게임화 — 우주 꾸미기 (Phase 2) — 완전 검정 우주에서 시작, 활동하며 포인트를 모아 아이템으로 꾸며가는 Cookie Clicker 스타일. 66개 아이템 (해금 5 / 별 5 / 큰별 4 / 푸른별·주황별 각 3 / 반짝이는별 5 / 은하수 7 / 성운 5 / 별똥별 8 / 천체 5 / 별자리 1 / 캐릭터 4 / 이벤트 7 / 메타 1 / Legendary 3) + 14 카테고리 탭. 신규 사용자 환영 보너스 200P + 이벤트 훅 자동 포인트 획득(질문 +3, 도구 +0.5, 에이전트 완료 +10, 응답 +1) → ⭐ 포인트 배지 클릭 시 🛒 상점 모달 → 구매 즉시 우주에 반영 (SSE). 천체 5종(달/행성/펄사/쌍성/우주정거장) + 캐릭터 효과 4종(후광/잔상/점프/팡파르) + 연속 스트릭 배지. 가격 일괄 ×2, 삭제 아이템 DEPRECATED_ITEMS fallback 환불. 프리뷰 모드 지원(?preview=empty/mid/full).
• 🎮 미니게임 — 응답 대기 중 즐기는 미니게임 3종 (🐍 Snake, 🔢 2048, 🐦 Flappy Bird). 최고점수 저장, Snake/2048 이어하기 지원. 🎮 버튼으로 모달 열기
• 성능 최적화 — 탭 비활성 시 애니메이션 자동 정지, renderAll 디바운스, 이벤트 마스터 틱 single-interval, DOM 파티클 상한 가드

요구사항

• macOS / Windows (Linux 미테스트)
• Node.js 16+ (node --version으로 확인)
• Claude Code CLI

설치

1. 파일 배치

# ~/.claude/agent-viz/ 에 프로젝트 파일 배치
git clone https://github.com/oy-snowwwww/claude-agent-viz.git ~/.claude/agent-viz

2. 에이전트 디렉토리 생성

에이전트 .md 파일을 넣을 디렉토리가 없다면 생성합니다 (이미 있으면 건너뛰세요):

mkdir -p ~/.claude/agents

3. 실행 권한 부여

chmod +x ~/.claude/agent-viz/start.sh
chmod +x ~/.claude/agent-viz/hook-handler.sh

4. CLI 별칭 설정 (선택)

# ~/.zshrc 또는 ~/.bashrc에 추가
alias claude-agents="bash ~/.claude/agent-viz/start.sh"

5. Claude Code 훅 설정

~/.claude/settings.json을 열고 hooks 키 안에 아래 이벤트들을 추가합니다.

이미 다른 hooks가 있다면? 기존 이벤트 배열에 항목을 추가하세요. 예를 들어 SessionStart에 이미 훅이 있으면, 해당 배열에 아래 항목을 병합합니다. 처음 설정하는 경우 아래 전체를 그대로 붙여넣으면 됩니다.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/start.sh auto"
          },
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/hook-handler.sh session_start"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/hook-handler.sh thinking_start"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/hook-handler.sh thinking_end"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/hook-handler.sh session_end"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Agent",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/hook-handler.sh agent_start"
          }
        ]
      },
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/hook-handler.sh tool_use"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Agent",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/agent-viz/hook-handler.sh agent_done"
          }
        ]
      }
    ]
  }
}

설정 후 Claude Code를 재시작하거나 새 세션을 시작해야 훅이 반영됩니다.

사용법

서버 관리

claude-agents          # 서버 시작 + 브라우저 열기
claude-agents stop     # 서버 종료
claude-agents status   # 현재 상태 확인
claude-agents on       # 세션 시작 시 자동 실행 ON
claude-agents off      # 세션 시작 시 자동 실행 OFF

대시보드 UI

헤더 버튼

에이전트 토글

각 에이전트 카드의 토글 스위치로 프로젝트별 에이전트 활성화를 제어합니다.

OFF하면? 프로젝트 CLAUDE.md 끝에 아래 마커가 자동 삽입됩니다:

<!-- agent-viz:agents coder, qa -->
<!-- 이 프로젝트에서는 위 에이전트만 사용한다 -->

Claude는 이 주석을 읽고 해당 에이전트만 사용합니다. 기존 CLAUDE.md 내용은 건드리지 않습니다.

• Master 작업 중이거나 해당 에이전트가 실행 중일 때 토글 변경 불가 (잠금)
• 전체 ON 시 제한 해제 (마커 제거)
• 전체 OFF 시 에이전트 미사용 (none)

세션 히스토리

종료된 세션을 자동으로 저장하고 나중에 검색/조회할 수 있습니다. 🕐 버튼으로 히스토리 모달 열기.

자동 저장 내용

• 질문 프롬프트 원문 (최대 500자, 민감정보 자동 마스킹)
• 질문별 응답 요약 (Claude Code transcript JSONL 파싱으로 추출)
• 에이전트 사용 통계 (타입별 실행 수, 평균 시간)
• 도구 사용 카운트 + 파일 접근 횟수 (Top 10)
• 응답 시간 (평균, 최대)

검색/필터

• 키워드 검색 — 프롬프트, 응답 요약, 파일명, 세션명 전역 매칭 + 하이라이트
• 날짜 필터 — 전체 / 오늘 / 최근 3일 / 최근 7일
• 에이전트 필터 — 특정 에이전트를 호출한 세션만 표시

용량 가드

• 7일 이상 오래된 파일 자동 삭제
• history/ 디렉토리 10MB 초과 시 오래된 순으로 추가 삭제
• 세션당 최대 100개 질문까지만 개별 저장 (그 이후는 통계만 누적)
• 1시간 주기로 cleanHistory 자동 실행

사용 안 함 토글 (🔒) — 이후 종료되는 세션을 디스크에 저장하지 않음

• ON: saveSessionHistory()가 skip되어 history/ 에 새 파일이 생기지 않음 (실시간 UI는 메모리 기반이라 정상 동작)
• OFF: 이후 세션부터 다시 정상 저장
• ~/.claude/agent-viz/privacy 파일로 상태 관리 (서버 재시작 후에도 유지)
• 토글은 "기록 여부"만 제어 — 이미 저장된 히스토리 정리는 별도의 🗑 전체 삭제 버튼 또는 행 단위 ✕ 삭제 사용

민감정보 자동 마스킹

• OpenAI/Anthropic 키 (sk-*)
• GitHub 토큰 (ghp_*, ghs_*, gho_*, ghu_*, github_pat_*)
• Slack 토큰 (xoxb-* 등)
• AWS Access Key (AKIA*)
• JWT (3 segment base64url)
• Bearer 토큰 헤더

/rename 자동 동기화

Claude Code 세션에서 /rename <이름> 명령을 실행하면 대시보드 탭 이름이 자동으로 갱신됩니다.

동작

1. /rename 명령은 Claude Code transcript(<sessionId>.jsonl)에 기록됨
2. 다음 thinking_start 시 서버가 transcript 끝에서 가장 최근 /rename 명령 추출
3. 현재 세션 이름과 다르면 업데이트 + SSE로 브라우저에 즉시 반영
4. _renamedFromTranscript 플래그로 이후 훅 이벤트의 cwd basename 덮어쓰기 방지

문제 해결

주의사항

CLAUDE.md는 git에 올리지 마세요

에이전트 토글 기능이 프로젝트 CLAUDE.md에 마커를 씁니다. 프로젝트의 .gitignore에 아래 항목을 추가하세요:

CLAUDE.md
.claude/
.mcp.json

설정

환경변수

파일 구조

~/.claude/agent-viz/
├── public/                    # 클라이언트 정적 파일 (브라우저에 서빙)
│   ├── index.html             # UI 마크업 + <script> 태그만 (인라인 JS 없음)
│   ├── css/
│   │   └── styles.css         # 전체 스타일
│   └── js/                    # JS 모듈 (<script> 순서 로딩)
│       ├── lang.js            # i18n (한/영) 문자열 관리, t(key) 함수
│       ├── constants.js       # 상수 (색상, 도구 목록, 픽셀맵, Village Tier, 게임화 ITEMS 카탈로그)
│       ├── state.js           # 전역 상태 (sessions, liveInstances, currentVillageTier 등)
│       ├── utils.js           # 순수 헬퍼 (esc, shade, buildPix) + Village Tier 감지 + 글로벌 툴팁
│       ├── village.js         # 마을(우주) 모드 — 별/은하수/nebula/별똥별 (게임 버프 적용)
│       ├── creature.js        # 픽셀 캐릭터 자율 행동 (roam/sleep/blink)
│       ├── history.js         # 세션 히스토리 UI (검색·필터·삭제·cwd 칩)
│       ├── notifications.js   # 브라우저 알림
│       ├── animations.js      # 시각 이펙트 (sparks/flyDot/celebrate)
│       ├── event-ticks.js     # 게임화 이벤트 마스터 틱 (10종 주기 이벤트 + Twin Moons 상시 오버레이)
│       ├── points.js          # 게임화 포인트 — 배지 렌더 + SSE 수신 + 버프 동기화 (프리뷰 모드 격리)
│       ├── shop.js            # 🛒 상점 모달 — 12 카테고리 탭, 구매 (Epic/Legendary 2단계 확인), 환불 초기화
│       ├── games.js           # 🎮 미니게임 공통 (모달, 메뉴)
│       ├── games/             # 미니게임 개별 파일
│       │   ├── snake.js       # Snake (localStorage 저장, 이어하기)
│       │   ├── 2048.js        # 2048 (localStorage 저장, 이어하기)
│       │   └── flappy.js      # Flappy Bird
│       ├── api.js             # 서버 API 호출 래퍼 (fetch/save/delete)
│       ├── log.js             # 로그 패널 (addLog, renderLogs, fmtTime)
│       ├── sessions.js        # 세션/탭 관리 (register/switch/rename/reorder + 이벤트 위임)
│       ├── workspace.js       # 워크스페이스 + 에이전트 목록 + Master 카드 렌더 (Ambient 버프 적용)
│       ├── panels.js          # Activity + Timeline 패널 렌더
│       ├── stats.js           # Daily Stats 드롭다운 + SSE 실시간 업데이트
│       ├── mcp-hooks.js       # MCP 서버 + Hooks 사이드바 렌더
│       ├── modal.js           # 에이전트/마스터 설정 모달
│       ├── server-control.js  # 재시작/종료/도움말/토스트
│       ├── events.js          # SSE 연결 + 이벤트 타입별 핸들러 (handleLiveEvent)
│       └── main.js            # 부트스트랩 — Theme, renderAll, Logo, init, Page Visibility, 게임 버프 초기화 + 프리뷰 모드
├── lib/                       # 서버 모듈 (server.js에서 분리)
│   ├── state.js               # 공유 상태 컨테이너 (sessions, sseClients, statsData, pointsData)
│   ├── utils.js               # 순수 유틸 (maskSecrets, truncate, isPrivacyOn, _ymd)
│   ├── security.js            # 보안 가드 (guardMutate, readBodySafe, isValidCwd, safePath)
│   ├── frontmatter.js         # YAML Frontmatter 파서
│   ├── sse.js                 # SSE 브로드캐스트
│   ├── agents.js              # 에이전트/MCP/Hooks CRUD
│   ├── stats.js               # 일일 통계
│   ├── gamification.js        # 게임화 (포인트/성취/레벨/구매)
│   ├── session-tracker.js     # 세션 트래커
│   └── history.js             # 히스토리 저장/파싱
├── server.js                  # Node.js HTTP 서버 (라우팅 + lib 모듈 조합)
├── hook-handler.sh            # Claude Code 훅 → 서버 이벤트 브릿지
├── start.sh                   # 서버 시작/종료/상태 CLI
├── enabled                    # 자동 실행 플래그 (파일 존재 여부)
├── privacy                    # Privacy 모드 플래그 (파일 존재 여부)
├── sessions/                  # 활성 세션 PID 파일
├── history/                   # 세션 히스토리 JSON (7일·10MB 가드, 1시간 주기 정리)
├── agent-stats.json           # 일일/주간/누적 통계
└── points.json                # 게임화 포인트 (잔고·누적·인벤토리, 런타임 — .gitignore 처리)

화면에 뭐가 어디서 오는가

대시보드에 보이는 각 영역이 어떤 파일을 읽는지 매핑입니다.

파일을 만들면 → 대시보드에 자동 반영

~/.claude/agents/my-agent.md 생성  →  좌측 AGENTS에 카드 표시 + 워크스페이스에 캐릭터 등장
~/.mcp.json에 서버 추가            →  좌측 MCP SERVERS에 표시
~/CLAUDE.md 수정                   →  MASTER에서 편집/확인 가능

Claude Code 설정 구조 안내

이 도구는 Claude Code의 설정 파일들과 연동됩니다. 처음이라면 아래 구조를 참고하세요.

~/
├── CLAUDE.md                      # 전역 설정 (모든 프로젝트에 적용)
└── .claude/
    ├── settings.json              # Claude Code 설정 (hooks, permissions 등)
    ├── settings.local.json        # 로컬 설정 (gitignore 대상)
    ├── agents/                    # 에이전트 정의 (.md 파일)
    │   ├── coder.md
    │   ├── reviewer.md
    │   └── ...
    └── agent-viz/                 # ← 이 프로젝트

에이전트 파일 예시 (~/.claude/agents/coder.md)

---
name: coder
description: 백엔드 코드 구현
tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"]
model: sonnet
---

당신은 백엔드 개발자입니다.
코드를 구현하고 테스트를 작성합니다.

프로젝트 CLAUDE.md 예시 (<프로젝트>/CLAUDE.md)

# 프로젝트 설정

## 기본 규칙
- Kotlin/Spring Boot 프로젝트
- 테스트는 JUnit5 사용

## 빌드
- ./gradlew build

MCP 서버 설정 (~/.mcp.json)

{
  "mcpServers": {
    "github-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

기술 스택

• 의존성 없음 — npm 패키지, 외부 CDN 없이 Node.js 내장 모듈만 사용
• 정적 파일 서빙 — public/ 하위에 클라이언트 자산 (HTML/CSS/JS) 분리, 서버가 직접 서빙
• SSE (Server-Sent Events) — 실시간 이벤트 스트리밍
• Vanilla JavaScript — 프레임워크 없는 순수 JS, 빌드 시스템 없음 (ES 모듈 대신 <script> 순서 로딩으로 8개 파일 분리)
• 단위/통합 테스트 — Node 18+ 내장 node:test (의존성 0). 124 tests — 서버 단위 81개 + HTTP 통합 18개(child 서버 spawn + 실제 API) + 클라이언트 순수 함수 25개(constants/utils). 실행: bash test/run.sh [unit|integration|all]

라이선스

MIT