sudokku/gsd-watch

Claude Code를 위한 실시간 GSD 프로젝트 상태 사이드바 — 터미널 내에서 항상 표시됩니다.

데모는 편의를 위해 속도를 높였으며 일부 분량을 편집했습니다. 실제 micro-ffmpeg 프로젝트 세션에서 녹화되었습니다.

읽기 전용 tmux/cmux 사이드바로, GSD 프로젝트 트리를 실시간으로 렌더링합니다 — 단계(phases), 계획(plans), 상태 아이콘(status icons), 라이프사이클 배지(lifecycle badges)를 포함하며, 파일 변경 후 1초 이내에 업데이트됩니다. Claude Code 옆에 배치되어 컨텍스트(context)를 전환하지 않고도 현재 위치를 항상 파악할 수 있습니다.

OS / Arch	tmux	cmux
macOS arm64	✓	✓
...
cmux는 macOS 전용입니다; Linux 사용자는 tmux를 사용합니다.

tmux 또는 cmux — 둘 중 하나는 실행 중이어야 합니다.
Claude Code가 tmux 또는 cmux 세션 내부에서 실행 중이어야 합니다.
.planning/ 디렉토리가 있는 GSD v1 프로젝트여야 합니다.

옵션 A — 바이너리 다운로드 (권장, Go 설치 불필요):

# Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/sudokku/gsd-watch/releases/latest/download/gsd-watch-darwin-arm64 \ 
-o ~/.local/bin/gsd-watch && chmod +x ~/.local/bin/gsd-watch
...

Linux:

# Linux arm64
curl -L https://github.com/sudokku/gsd-watch/releases/latest/download/gsd-watch-linux-arm64 \ 
-o ~/.local/bin/gsd-watch && chmod +x ~/.local/bin/gsd-watch
...

~/.local/bin이 $PATH에 포함되어 있는지 확인하세요. 필요한 경우 쉘 프로필(shell profile)에 다음을 추가하세요:

export PATH="$HOME/.local/bin:$PATH"

그 다음 /gsd-watch 슬래시 명령어를 Claude Code에 설치하세요:

mkdir -p ~/.claude/commands
curl -L https://raw.githubusercontent.com/sudokku/gsd-watch/main/commands/gsd-watch.md \ 
-o ~/.claude/commands/gsd-watch.md

옵션 B — 소스에서 빌드:

git clone https://github.com/sudokku/gsd-watch.git
cd gsd-watch
make all # macOS 바이너리 빌드 + ~/.local/bin/gsd-watch에 설치

그 다음 /gsd-watch 슬래시 명령어를 Claude Code에 설치하세요:

make plugin-install-global # 모든 프로젝트에서 사용 가능 (권장)
make plugin-install-local # 현재 프로젝트에서만 사용 가능

tmux에서 실행 중인 Claude Code 세션 내부에서 다음을 실행하세요:

/gsd-watch

이 명령을 실행하면 현재 프로젝트를 위한 gsd-watch가 실행되는 너비 35%의 우측 사이드 패인 (pane)이 열립니다. 포커스는 Claude Code 패인에 그대로 유지됩니다. GSD 단계가 진행됨에 따라 사이드바가 자동으로 업데이트되므로 수동으로 새로고침할 필요가 없습니다.

키	동작
j / ↓	아래로 이동
k / ↑	위로 이동
l / →	단계 확장 (Expand phase)
h / ←	단계 축소 (Collapse phase)
e	모두 확장 (Expand all)
w	모두 축소 (Collapse all)
?	도움말 오버레이 (Help overlay)
qq / Esc Esc	종료
Ctrl+C	강제 종료

해당 단계 디렉토리에 상응하는 GSD 라이프사이클 (lifecycle) 파일이 존재할 경우, 각 단계 아래에 배지 (Badge)가 나타납니다:

배지	단계	파일
💬	논의됨 (Discussed)	NN-CONTEXT.md
...

gsd-watch는 .planning/ 디렉토리를 fsnotify (재귀적, 300ms 디바운스 적용)를 통해 감시하며, 파일 변경 시마다 다시 렌더링 (re-render)합니다. 따라서 폴링 (polling) 없이도 트리 구조가 항상 최신 상태를 유지합니다.

make build-darwin # build/gsd-watch-darwin-arm64 + build/gsd-watch-darwin-amd64
make build-linux # build/gsd-watch-linux-arm64 + build/gsd-watch-linux-amd64
make build-all # 4개의 바이너리 모두 (darwin + linux)
...

정적 바이너리 (Static binary)이며, CGO를 사용하지 않고 tmux 또는 cmux를 제외한 런타임 의존성 (runtime dependencies)이 없습니다. Bubble Tea로 빌드되었습니다.

macOS Sequoia 참고 사항: Darwin 바이너리는 서명 (signed)되어야 하며, 그렇지 않으면 macOS가 실행 시 프로세스를 종료합니다. make build-darwin은 codesign을 통해 이를 자동으로 처리합니다. Linux 바이너리는 서명이 필요하지 않습니다. GitHub 릴리스 (releases)에서 다운로드한 바이너리는 이미 서명되어 있습니다.

버그, 기능 아이디어, 워크플로우 제안은 모두 환영합니다 — GitHub 이슈 (issue)를 열어주세요. 특히 다른 GSD 사용자들이 어떻게 활용하고 있는지, 그리고 무엇이 일상 업무에서 더 유용하게 만들 수 있을지에 대해 듣고 싶습니다.

MIT License