Atc.Claude.Kanban
브라우저 기반 보드를 통해 Claude Code 에이전트의 작업(tasks), 세션(sessions), 서브에이전트(subagents)를 모니터링하는 실시간 Kanban 대시보드입니다.
<p align="center">
<img src="https://raw.githubusercontent.com/atc-net/atc-claude-kanban/HEAD/docs/overview-dark.png" alt="Dashboard overview — dark theme" width="900">
</p>
보드 및 작업 (Board & tasks)
- 📊 실시간 Kanban 보드 — Claude가 작업하는 동안 작업(tasks)이 대기 중(Pending) → 진행 중(In Progress) → 완료됨(Completed)으로 흐릅니다.
- 📈 타임라인 보기 — 상태별로 색상이 지정된 작업 기간의 가로 막대와 마우스 오버 툴팁을 제공합니다.
- 🖱️ 드래그 앤 드롭 — 작업을 끌어다 놓아(dragging) 열 사이를 이동시킬 수 있습니다.
- 🔗 작업 의존성 — 스마트 배지 클리어링 기능과 함께 blockedBy/blocks 관계를 시각적으로 보여줍니다.
- 📦 자동 아카이브 — 오래된 세션(7일 초과, 활성 작업 없음)은 "보관됨(Archived)" 섹션으로 축소됩니다.
- 🚫 세션 숨기기 — 삭제하지 않고도 활성 목록에서 세션을 일시적으로 숨깁니다.
세션 및 사이드바 (Sessions & sidebar)
- 🗂️ 프로젝트 그룹화 — 세션을 프로젝트별로 그룹화하며, 접을 수 있는 헤더 아래에 활성/총 개수가 표시됩니다. 해당 섹션에는 활성 작업이 배치되면 자동으로 확장됩니다.
- 📌 세션 고정 — 세션을 상단의 접을 수 있는 그룹에 고정할 수 있습니다(저장됨).
- 🎯 활동 상태 — 각 세션별로 생각 중(thinking)/대기 중(waiting)/유휴(idle)/오류(error) 표시기가 있으며, 이는 JSONL에서 파생됩니다.
- 🏁 세션 목표 — 활성
/goal 조건은 카드 부제목과 세션 정보 모달에 표시됩니다.
- 🧮 컨텍스트 창 측정기 — 세션별로 컨텍스트 창이 얼마나 가득 찼는지 보여주는 막대(200K 또는 추론된 1M).
- 💰 토큰 및 비용 추적 — 누적된 토큰 사용량과 세션별 모델 인식 비용을 제공합니다.
- 🔍 퍼지 검색 — 세션, 작업, 설명 및 프로젝트 경로 전반에 걸쳐 수행할 수 있습니다.
- 📓 스크래치패드 — 로컬 저장소(localStorage) 지속성과 사이드바 배지를 갖춘 세션별 메모입니다.
인사이트 패널 (Insight panels)
- 💬 세션 메시지 로그(Session message log) — 전체 도구 인자 상세 정보(MCP 포함)가 담긴 기록, 사용자 질문 답변(AskUserQuestion), 이미지 첨부 파일
- 💵 사용량 분석(Usage breakdown) — 모델별로 메인 세션과 각 서브 에이전트 간의 토큰/비용 분할 내역
- 🔧 도구 통계(Tool statistics) — 성공/실패/거부된 도구 호출 건수 분석 및 출력 영향력 공유
- 📝 계획 보기(Plan viewer) — Mermaid.js 다이어그램 렌더링을 통해 Claude Code 계획 확인 및 열기
에이전트 및 팀(Agents & teams)
- 🤖 에이전트 팀(Agent teams) — 색상 코드가 지정된 팀원 목록, 소유자 필터링, 멤버 배지
- 🧩 서브 에이전트 가시성(Subagent visibility) — 설명, 이름 및 클립보드 복사 가능한 프롬프트가 포함된 활성 서브 에이전트
- ⚙️ 워크플로우 보기(Workflow viewer) — 선언된 단계(phases), 저널에서 파생된 상태를 가진 에이전트 명단, 스크립트 소스
실시간 및 실시간 기능(Live & real-time)
- 📡 서버 전송 이벤트(Server-Sent Events) — 파일 관찰을 통한 즉각적인 업데이트 (폴링 불필요)
- ⚡ 스마트 폴링(Smart polling) — 탭이 숨겨져 있을 때는 폴링을 건너뛰고 포커스가 돌아왔을 때 최신 상태를 따라잡음
- 🔔 데스크톱 알림(Desktop notifications) — 작업 완료 시 브라우저 알림 및 사운드 차임 제공
- ✏️ 편집기에서 열기(Open in editor) — 메시지 로그의 파일 경로를 클릭하여 VS Code에서 열기
인터페이스 및 플랫폼(Interface & platform)
- ⌨️ 키보드 탐색(Keyboard navigation) — vim 스타일(hjkl) 및 화살표 키 사용, 사이드바/보드 포커스 전환
- 🌙 다크/라이트 테마(Dark / light themes) — 시스템 환경 설정 감지 및 17가지 테마 색상 선택기 제공 (Gruvbox, Catppuccin, Tokyo Night, Dracula, Nord 등)
- 🔌 자동 포트 검색(Auto-port discovery) — 기본 포트가 사용 중일 때 사용 가능한 포트를 찾아줌
- 🔄 자동 업데이트(Auto-update) — 시작 시 NuGet을 통해 새 버전 확인
📋 요구 사항(Requirements)
- .NET 10 SDK (또는 이후 버전, RollForward를 통해 접근 가능)
- **작업 도구(task tools)**가 활성화된 Claude Code 필요 — 아래 [작업 도구 옵트인(Task tools opt-in)] 참조
칸반 보드는 Claude Code가 ~/.claude/tasks/ 경로 아래에 작성하는 작업 파일을 읽습니다. 이 파일들은 세션이 Claude Code의 TaskCreate / TaskGet / TaskUpdate / TaskList 도구를 가지고 있는 동안에만 존재하며, Claude Code 도구 참고 자료에 따르면 다음 세 가지 조건이 모두 충족될 때 기본적으로 해당 도구들이 제외됩니다:
- Claude Code가 v2.1.233 이상이고,
- 세션이 Opus 4.8, Sonnet 5, Fable 5, Mythos 5 또는 이 계열의 이후 버전으로 실행되며,
- 옵트인(opt-in) 설정이 없는 경우입니다.
해당 모델들은 작성된 체크리스트 없이 다단계 작업을 추적하며, 도구 정의는 컨텍스트를 소모하므로 Claude Code가 이를 생략합니다. 반면, 다른 모델(예: Opus 4.7)에서는 네 가지 작업 도구가 기본으로 제공되며 옵트인 설정이 필요하지 않습니다.
증상: 사이드바에는 여전히 세션과 서브 에이전트, 메시지 로그, 토큰/비용 추적, 도구 통계 및 워크플로우 뷰어가 모두 작동하는 것처럼 보이지만(이들은 작업 파일이 아닌 세션 기록을 읽음), 칸반 열과 타임라인 뷰는 비어 있게 유지됩니다. 이는 아무것도 작업 파일을 작성하지 않기 때문입니다.
옵트인 하려면, Claude Code 세션에서 CLAUDE_CODE_ENABLE_TODO_TOOLS=1을 설정해야 합니다. 다음 중 한 가지 방법으로 영구적으로 설정할 수 있습니다. ~/.claude/settings.json 파일에:
{
"env": {
"CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"
...
}
또는 실행 시마다 설정할 수 있습니다:
# PowerShell
$env:CLAUDE_CODE_ENABLE_TODO_TOOLS = "1"; claude
CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude
명령줄에서 작업 도구 중 아무거나 지정하는 것만으로도 세션이 옵트인됩니다. 예를 들어, claude --allowedTools TaskCreate를 사용하거나, 사용하려는 다른 도구들과 함께 claude --tools ...에 포함할 수 있습니다(이 플래그는 기본 내장 도구를 지정된 도구로 제한합니다). 백그라운드 세션과 웹상의 Claude Code는 모델에 관계없이 항상 작업 도구를 얻게 됩니다.
서브 에이전트(subagent)는 부모 세션(parent session)이 해당 작업 도구(task tools)를 가지고 있을 때만 받으며, 설령 서브 에이전트가 다른 모델을 실행하더라도 마찬가지입니다. 따라서 세션을 활성화하면 보드의 서브 에이전트 및 에이전트-팀 행에 대한 작업 데이터도 복원됩니다.
🚀 시작하기 (Getting Started)
설치 (Install)
dotnet tool install -g atc-claude-kanban
실행 (Run)
# 대시보드 시작 (기본값: http://localhost:3541)
atc-claude-kanban
...
이후 브라우저를 열고 http://localhost:3541로 이동하여 Claude Code 작업을 실시간으로 확인하세요.
<p align="center">
<img src="https://raw.githubusercontent.com/atc-net/atc-claude-kanban/HEAD/docs/cli-started.png" alt="CLI startup banner" width="500">
</p>
자동 포트(Auto-port): 기본 포트를 사용하는데 이미 사용 중인 경우, 도구는 최대 10개의 연속된 포트(3541, 3542, ...)를 자동으로 시도합니다. --port를 명시적으로 지정하면 도구가 즉시 실패합니다(fails fast).
기본값인 3541은 동적 예약 포트와의 충돌을 피하기 위해 Windows 제외 TCP 범위(3422–3521) 밖에 위치합니다.
✨ 기능 (Features)
📊 칸반 보드 (Kanban Board)
작업 상태를 보여주는 세 개의 열로 구성된 보드로, 실시간 업데이트가 이루어집니다:
| 열 (Column) | 설명 (Description) |
|---|
| Pending | 시작을 기다리는 작업 |
| ... | |
📈 타임라인 보기 (Timeline View)
헤더의 보기 토글 버튼을 사용하여 칸반(Kanban) 보기와 타임라인(Timeline) 보기 간에 전환할 수 있습니다:
- 가로 막대는 각 작업의 생성부터 마지막 업데이트까지의 기간을 보여줍니다.
- 상태별로 색상 코딩됩니다: 회색 (대기 중), 빛나는 주황색 (진행 중), 녹색 (완료).
- 마우스를 올리면 작업 이름, 상태, 기간 및 시작 시간이 표시되는 툴팁이 나타납니다.
- 막대를 클릭하면 작업 상세 패널이 열립니다.
- 시간 축은 데이터 범위에 맞춰 조정됩니다 (초/분/시간/일).
- 보기 설정은 페이지 새로고침 시에도 유지됩니다.
<p align="center">
<img src="https://raw.githubusercontent.com/atc-net/atc-claude-kanban/HEAD/docs/timeline-dark.png" alt="Timeline view" width="900">
</p>
🔔 데스크톱 알림 (Desktop Notifications)
헤더의 종 모양 아이콘을 클릭하여 브라우저 알림을 활성화하세요:
📦 자동 보관(Auto-Archive)
진행 중인 작업이 없는 7일 이상 경과된 세션은 자동으로 보관됩니다:
- 보관된 세션은 사이드바 하단에 접을 수 있는 “보관됨 (N)” 섹션에서 확인할 수 있습니다.
- 시각적 구분을 위해 불투명도(opacity)가 50%로 어둡게 처리됩니다.
- 확장/축소 상태는 페이지 새로고침에도 유지됩니다.
- 검색 중이거나 활성 세션으로 필터링할 때는 숨겨집니다.
🤖 에이전트 팀(Agent Teams)
Claude Code가 에이전트 팀을 생성하면, 대시보드는 다음 정보를 표시합니다:
- 팀원별 색상 코딩된 소유자 배지(owner badges)
- 소유자 필터링 드롭다운 메뉴
- 멤버 상세 정보가 포함된 팀 정보 모달(modal)
- 에이전트별 작업 수량
<p align="center">
<img src="https://raw.githubusercontent.com/atc-net/atc-claude-kanban/HEAD/docs/session-info-dark.png" alt="팀원과 멤버별 작업 수를 보여주는 팀 세션 정보 모달" width="900">
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/atc-net/atc-claude-kanban/HEAD/docs/team-board-dark.png" alt="소유자 색상이 적용된 작업과 서브 에이전트 푸터가 있는 팀 보드" width="900">
</p>
🧩 서브 에이전트(Subagents)
클로드 코드가 Task 툴을 통해 서브 에이전트를 생성할 때 대시보드는 다음 내용을 표시합니다:
- 사이드바에 활성 서브 에이전트 개수 배지 (서브 에이전트가 실행 중일 때만 표시)
- 칸반 컬럼 아래의 접이식 서브 에이전트 패널. 이 패널에는 상태 점, 모델 정보 및 설명이 포함됩니다.
- 부모 세션의 Agent 툴_use 블록에서 추출된 에이전트 이름과 간략한 설명
toolUseResult 항목을 통한 포그라운드(Foreground) 에이전트 상관관계 표시- 작업 프롬프트에 대한 복사 버튼 및 확장/스크롤 가능한 상세 보기
- 과거 서브 에이전트를 볼 수 있는 "모두 보기" 토글 (기본값: 활성 에이전트만)
- 경로는
~/.claude/projects/{hash}/{sessionId}/subagents/의 JSONL 트랜스크립트 파일에서 파싱됩니다.
- **워크플로우 서브 에이전트(Workflow subagents)**도 포함됩니다. 이들은 Workflow 툴에 의해 생성되며, 해당 트랜스크립트는 한 단계 깊은 곳인
subagents/workflows/{runId}/에 위치합니다. 워크플로우 에이전트는 시각적으로 구별하기 위해 ⚙ workflow 배지를 가지며, 확장된 상세 보기에는 실행 ID(run id)가 표시됩니다. 출력 스키마를 받은 워크플로우 에이전트는 강제적인 StructuredOutput 호출로 종료되며 텍스트 답변을 작성하지 않으므로, 그 구조화된 결과가 에이전트의 응답으로 표면화됩니다.
<p align="center">
<img src="https://raw.githubusercontent.com/atc-net/atc-claude-kanban/HEAD/docs/workflow-subagents-dark.png" alt="Subagent panel listing workflow-spawned agents alongside a regular subagent" width="900">
</p>
⚙️ 워크플로우 뷰어 (Workflow Viewer)
**워크플로우 툴(Workflow tool)**을 사용한 세션은 기어 모양 배지를 받습니다. 이를 클릭하거나 W를 누르면 워크플로우 뷰어가 열립니다:
- 단계 개요(Phase outline) — 스크립트의
meta 블록에 선언된 단계들과 그 상세 라인들
- 에이전트 명단(Agent roster) — 실행 중인 모든 에이전트와 해당 작업(task), 모델(model), 도구 개수(tool count), 지속 시간(duration), 그리고 '완료된 N/M 에이전트 비율'을 보여줍니다. 상태는 실행의
journal.jsonl에서 가져오며, 이는 에이전트가 실제로 완료했는지 여부를 기록하는 유일한 기록입니다. (스크립트) 전사(transcript) 타임스탬프는 단지 마지막으로 작성한 시점만 알려줄 뿐입니다.
- 스크립트 소스(Script source) — 기본적으로 구문 강조 표시되고 접혀 있으며, 에디터에서 열기 버튼이 있습니다.
- 세션에 여러 워크플로우가 있는 경우 선택기(picker)가 먼저 나타납니다.
meta 블록은 소스를 패턴 매칭하여 읽으며, 스크립트는 절대 실행되지 않습니다.
로스터는 평면적입니다: 어떤 에이전트가 어느 단계에서 실행되었는지는 런타임(runtime)에만 존재하며 디스크에 기록되지 않습니다.
<p align="center">
<img src="https://raw.githubusercontent.com/atc-net/atc-claude-kanban/HEAD/docs/workflow-run-dark.png" alt="선언된 단계, journal에서 파생된 상태를 가진 에이전트 명단, 그리고 구문 강조 표시된 스크립트 소스를 보여주는 워크플로우 뷰어" width="900">
</p>
💬 세션 메시지 로그(Session Message Log)
도구 모음의 채팅 아이콘 또는 Shift+L로 토글합니다:
