Claude Code 진행 상황을 실시간으로 추적하는 deadhd

Claude Code에 긴 작업을 맡긴 뒤 다른 세션을 보고 돌아오면, 어디까지 끝났는지부터 다시 확인하게 됩니다. 코드를 작성하는 중인지, 테스트에서 막혔는지, 내 승인을 기다리는지 알려면 터미널 로그를 거슬러 올라가야 할 때도 있습니다.

deadhd 는 이런 상황에서 진행 상황을 따로 보여 주는 Claude Code 플러그인입니다. 완료한 단계, 진행 중인 단계, 남은 단계를 체크리스트로 정리하고 여러 세션을 한 페이지에 모아 볼 수 있습니다. 브라우저를 열기 번거로우면 터미널 안의 짧은 상태 표시로도 확인할 수 있습니다. 여기서 HUD 는 작업 화면을 떠나지 않고 현재 상태를 확인하는 표시 영역을 뜻합니다.

아래는 저장소의 README를 바탕으로 정리한 기능과 사용 흐름입니다. 직접 실행한 사용기는 아닙니다.

작업 단계와 세션 상태는 어떻게 다를까

먼저 구분할 것은 작업 진행 상황과 세션 상태 입니다. deadhd는 두 정보를 함께 보여 주지만 정보를 만드는 방식은 다릅니다.

예를 들어 작업 단계에는 “테스트 실행 중”이라고 적혀 있는데 실제 세션은 명령 실행 승인을 기다리고 있을 수 있습니다. 이때 상태 표시를 보면 테스트가 오래 걸리는 것인지, 사람이 승인해야 다음으로 넘어가는 것인지 구분할 수 있습니다.

이벤트를 받는 장치를 훅(hook) 이라고 합니다. 사용자가 요청을 보냈을 때, 도구를 실행했을 때, 응답이 끝났을 때 같은 시점에 상태를 기록합니다. 덕분에 Claude가 체크리스트 갱신을 놓쳐도 승인 대기나 마지막 도구 정보는 별도로 표시할 수 있습니다. 다만 이것이 모든 작업 단계의 완료 여부를 자동으로 검증한다는 뜻은 아닙니다.

내 작업 환경에 맞는 화면 고르기

표시 위치는 세 가지입니다. 우선 터미널 안에서 간단히 볼지, 브라우저에서 단계별 내용을 자세히 볼지 고르면 됩니다.

band는 다른 창을 열지 않고 지금 무슨 일을 하는지 확인하려는 경우에 어울립니다. 작업 단계와 관련 파일까지 읽으려면 html 페이지가 편합니다. Orca처럼 브라우저 패널이 있는 앱에서는 터미널 옆에 띄워 둘 수 있고, 시스템 브라우저로 열어도 됩니다.

이미지: deadhd 저장소

브라우저 페이지 안에서는 같은 데이터를 네 가지 모양으로 바꿔 볼 수 있습니다. 표시 위치를 고르는 위의 세 가지 방식과는 별도 설정입니다.

• 원본: 흐름도와 단계별 카드를 모두 보여 줍니다.
• 스트립: 전체 단계를 한 줄의 점으로 줄이고 현재 단계의 카드를 펼칩니다.
• 타임라인: 단계를 세로로 나열하고 완료 시각이나 예상 시간을 붙입니다.
• 타일: 완료 수, 남은 시간, 완료 예상 시각을 숫자로 먼저 보여 줍니다.

보기 전환은 이미 받은 데이터로 브라우저가 처리하므로 추가 토큰을 쓰지 않습니다. 체크리스트 내용을 Claude가 작성하고 갱신하는 작업까지 토큰이 들지 않는다는 의미는 아닙니다.

여러 세션과 병렬 작업 확인하기

세션마다 페이지를 열어 보는 것이 번거롭다면 허브 를 사용할 수 있습니다. 이 컴퓨터의 세션을 한 페이지에 모으고, 권한 승인 대기나 신호가 없는 세션을 작업 중인 세션보다 위에 배치합니다. 같은 상태라면 오래 기다린 세션부터 보여 줍니다.

허브는 지금 사람이 확인해야 할 세션을 찾는 데 유용합니다. 여러 사람이 쓰는 컴퓨터나 원격 서버의 모든 세션을 모으는 팀 대시보드 기능으로 소개된 것은 아닙니다. README에서는 상태 파일을 쓰는 1.8.0 이후 세션을 모은다고 설명합니다.

한 세션 안에서 여러 작업을 병렬로 진행할 때는 레인 보드 로 작업별 흐름을 볼 수 있습니다. 작업 하나를 한 행에 놓고 현재 단계, 작업자, 마지막 신호, 남은 시간 등을 표시하는 표입니다. 문서에서는 네 개 이상의 작업 단위를 병렬로 진행할 때 사용하는 구조로 설명합니다.

기본 정체 기준은 마지막 신호 이후 10분입니다. 브라우저가 경과 시간을 계산하므로 모델이 갱신을 멈춘 작업도 정체 상태로 표시할 수 있습니다. 다만 신호가 없다는 사실만으로 작업 실패가 확정되는 것은 아닙니다. 보드를 표시하려면 진행 데이터에 board 정보도 있어야 합니다.

설치하고 첫 진행 페이지 열기

필요한 것은 Claude Code와 python3입니다. deadhd의 Python 코드는 표준 라이브러리만 사용합니다. 설치 방법은 플러그인, 스킬 폴더 복사, Orca 공유 링크입니다. 처음에는 README에서 권장하는 플러그인 방식을 따라가면 됩니다.

Claude Code 세션 안에서 다음 두 명령을 순서대로 입력합니다.

/plugin marketplace add lcalmsky/deadhd
/plugin install deadhd@deadhd

첫 번째 명령은 플러그인을 받을 마켓플레이스를 등록하고 두 번째 명령이 deadhd를 설치합니다. 마켓플레이스 등록만으로 설치가 끝나는 것은 아닙니다.

설치한 뒤 진행 상황을 보고 싶은 작업 세션에서 다음 명령을 입력합니다.

/deadhd:deadhd

처음 실행하면 열기 위치, 표시 방식, 테마, 글꼴을 묻습니다. 브라우저에서 상세 내용을 보고 싶다면 표시 방식으로 html을, 터미널 위에서 간단히 보고 싶다면 band를 고르면 됩니다. 이후 작업 단계의 상태가 바뀔 때 Claude가 진행 데이터를 갱신합니다.

README에서는 “진행 상황 띄워줘”, “체크리스트로 보여줘”처럼 말로 요청하는 방법도 안내합니다. 문서의 /deadhd는 스킬 폴더 설치 때의 호출 이름이며 플러그인 설치에서는 /deadhd:deadhd를 사용합니다. 설정 변경과 허브 열기는 다음처럼 요청할 수 있습니다.

/deadhd:deadhd setup
/deadhd:deadhd hub

플러그인 설치와 스킬 폴더 복사는 둘 중 하나만 사용해야 합니다. 둘 다 설치하면 같은 플러그인이 두 번 로드되어 명령과 상태 갱신이 중복될 수 있습니다. 다른 설치 방법이 필요하면 README의 설치 안내 를 확인하면 됩니다.

화면을 읽을 때 알아둘 점

브라우저 페이지는 15초마다 데이터를 다시 받아 그립니다. 문서 전체를 다시 로드하지 않아 펼쳐 둔 항목과 스크롤 위치를 유지합니다. 따라서 “실시간”이라는 표현을 모든 화면 정보가 지연 없이 즉시 바뀐다는 뜻으로 받아들이지는 않는 편이 좋습니다.

완료한 단계에는 파일 경로, PR, 커밋, 테스트 통과 건수 같은 근거를 붙이도록 되어 있습니다. README의 완료 기준도 실행 결과가 확인된 단계만 done으로 표시하는 것입니다. 실제 결과를 확인해야 하는 작업이라면 완료 배지만 보고 끝내기보다 연결된 근거도 함께 읽어야 합니다.

완료 예상 시각도 확정된 마감은 아닙니다. 단계별 예상 시간과 실제 소요 시간의 이력을 쌓고, 3건부터 보정한 예상 시각을 함께 표시합니다. 긴 작업에서 시간을 가늠하는 참고 정보로 보면 됩니다.

기본 브라우저 페이지는 이 컴퓨터에서만 접속하는 127.0.0.1 주소의 정적 서버로 열립니다. 반면 Orca 아티팩트로 게시하는 기능은 공유 링크가 있는 페이지를 만드는 별도 동작입니다. 로컬에서 진행 상황을 보는 것과 다른 사람에게 공유하는 것을 구분해서 사용해야 합니다.

여러 Claude Code 세션을 오가며 승인 대기와 현재 단계를 자주 놓친다면 deadhd를 살펴볼 만합니다. 우선 한 세션에서 진행 페이지를 열어 보고, 필요한 정보가 짧은 상태 표시로 충분한지 단계별 근거까지 필요한지에 따라 화면을 고르면 됩니다.