문제 — Claude가 뭘 하는지 모르겠다

Claude Code를 본격적으로 쓰면서 한 가지 답답한 게 있었습니다 — 메인 에이전트에 명령을 내리면 그 안에서 여러 서브에이전트가 동시에 돌아가는데, 누가 뭘 하고 있는지 모르겠다는 거.

서브에이전트는 백그라운드에서 도구를 호출하고 파일을 읽고 결과를 반환합니다. 그게 끝나면 메인이 종합해서 답을 줍니다. 사용자(나)는 그 사이에 뭐가 일어났는지 거의 못 봅니다.

"리서치 봇이 지금 검색 중인지, 백테스트 봇이 데이터 처리 중인지, 누가 막혔는지 — 알면 작업 흐름 파악이 훨씬 쉬워질 텐데."

영감 — LUKE HEADQUARTERS 이미지

지인이 보내준 isometric 멀티에이전트 본부 이미지가 있었습니다. 캐릭터들이 각자 책상에서 일하고, 서로 클릭하면 프로필이 뜨는 그런 화면. 게임 대시보드 같은 느낌.

"이거 진짜 만들면 어떨까."

설계 — 2026-04-19 Phase 1

Phase 1은 기능 MVP에만 집중. 캐릭터 아바타·시각 디자인은 Phase 2로 미루고, 데이터 파이프라인 + 기본 대시보드부터.

[Claude Code 후크 이벤트] → status_writer.py → state.json
                                                    ↓
                          [브라우저 폴링 500ms] → dashboard.html
                                                    ↓
                          [Telegram 데몬 3s] → 모바일 라이브

핵심 파일들 (C:\Users\user\agents-hq\):

status_writer.py — Claude Code 후크 이벤트를 stdin으로 받아 state.json 업데이트. SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SubagentStop, Stop 6개 후크 wired.

state.json — 라이브 상태:

{
  "updated_at": "...",
  "session_id": "...",
  "agents": {
    "main": {
      "role": "팀장",
      "status": "thinking",
      "current_task": "...",
      "current_tool": "Read",
      "started_at": "...",
      "last_event_at": "...",
      "last_line": "...",
      "recent": [...]
    },
    "subagent-X": { ... }
  }
}

dashboard.html — 브라우저 대시보드. state.json을 500ms 마다 폴링, 에이전트 카드 렌더, 모바일 반응형.
serve.py — 작은 정적 HTTP 서버. 기본 0.0.0.0 바인딩 (LAN 접근 가능), --local로 localhost-only 모드.
telegram_status.py — 백그라운드 데몬. 상태를 단일 edit-in-place 텔레그램 메시지로 푸시. 3초 간격. 출장·외출 시 모바일에서 라이브로 작업 상태 확인.

~/.claude/settings.json에 후크 등록하면 끝. Claude가 도구 호출할 때마다 자동으로 이벤트가 흐릅니다.

결과 — 한눈에 보임

이제 Claude한테 명령 내리면:

메인 에이전트가 노란 "thinking" 상태로 떠
서브에이전트 스폰되면 새 카드가 나타남
각 카드에 현재 도구 (Read, Edit, Grep 등) + 진행 라인
끝나면 카드가 회색으로 fade
텔레그램에서도 동시에 보임

집에서 PC로 작업하다가 외출할 때 텔레그램만 켜둬도 진행 상황 모니터링됨.

Phase 2 — 시각화 (defer)

Anime-style 캐릭터 아바타 per agent
클릭 → 프로필 카드 (현재 task + role 설명 + 캐릭터 flavor line)
7개 역할: 팀장 / 리서치 / 빅데이터 / 백테스트엔지 / 전략리뷰어 / 전략심사관 / Python퀀트
Grok 또는 Midjourney로 캐릭터 sprites

이건 Phase 1이 작동하는 걸 며칠 써본 후 결정하기로 함. 시각이 정말 가치를 더하는지, 아니면 텍스트 카드만으로 충분한지.

Phase 3 — 작업 공간 시각화 (roadmap)

사용자 요청:

작업 지시 떨어지면 해당 에이전트들이 모이는 공간 구현
각자 일하는 모습 시각화
작업 중인 에이전트는 개성에 맞춘 반응형 말풍선
사무실 공간을 세션별로 분리

Sub-phase 분해:

3a: 말풍선 시스템 (~30분)
3b: 모임방 뷰 (~2시간)
3c: 캐릭터별 작업공간 배경 (~1시간)
3d: 세션 분리 (~2시간)
3e: 미세 작업 애니메이션 (~1시간)

총 6-7시간 분량. Phase 1이 충분히 검증된 후에.

교훈

빌드 인 퍼블릭의 한 가지 측면 — 자기가 만든 도구를 자기가 매일 씁니다. agents-hq는 처음 만든 날부터 오늘(2026-04-26)까지 매 세션 켜져 있습니다. 데이터가 쌓이고 패턴이 보입니다. 어떤 작업이 길게 걸리는지, 어떤 도구가 많이 호출되는지, 어디서 막히는지 — 본인의 작업 패턴이 객관적으로 보입니다.

이게 Context Engineering Kit (CEK) 프로젝트로 이어진 출발점이기도 합니다. agents-hq가 "현재 상태"를 보여준다면, CEK는 "지속되는 컨텍스트"를 만들어주는 도구. 둘이 짝입니다.

— Jack