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가 실행되는 너비 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