Claude Code가 작업을 마쳤는지 확인하려고 계속 Alt-Tab을 누르는 것이 번거로워 Craby를 만들었습니다. Craby는 macOS의 모든 앱/Space 상단에 떠 있는 작은 픽셀 아트 게(crab)로, Claude Code가 무엇을 하고 있는지 그대로 보여줍니다. 작업 중에는 작은 노트북으로 타이핑을 하고, 완료되면 축하를 하며, 제 도움이 필요할 때는 손을 흔듭니다. 이 프로젝트는 전적으로 Claude Code로 구축되었으며, 무료이며 오픈 소스(MIT)입니다. 이곳에 공유하는 주된 이유는 훅(hook) 시스템에 대해 배운 내용 때문이며, 이는 여러분이 직접 도구를 만들 때 유용할 수 있습니다:

1. 훅(Hooks)은 외부 통합을 사실상 무료로 만들어 줍니다. UserPromptSubmit, Stop, Notification, PostToolUse는 stdin을 통해 JSON 페이로드(session id, cwd, transcript path)와 함께 셸 명령어로 실행됩니다. Craby는 이러한 훅들이 작은 로컬 HTTP 서버로 curl 요청을 보내도록 설계되었습니다. 토큰 소모가 전혀 없으며, 모델의 컨텍스트(context)에 아무것도 들어가지 않습니다.

2. PermissionRequest 훅은 프롬프트를 관찰할 뿐만 아니라 프롬프트에 응답할 수도 있습니다. 훅은 연결을 열어둔 상태(long-poll)를 유지하며, 그동안 게(crab) 아래에는 허용/거부(Allow/Deny)를 선택하는 말풍선이 표시됩니다. 제가 클릭하면 그 결과가 훅의 stdout으로 반환되며, 터미널 대화창은 나타나지 않습니다. 디버깅 세션을 소모하게 만든 주의할 점은, 출력 형식이 permissionDecision이 아니라 hookSpecificOutput.decision.behavior라는 점입니다 (permissionDecision은 PreToolUse에서만 사용됩니다). 또한 약 45초 이내에 응답하지 않으면 훅은 아무것도 반환하지 않고 일반 프롬프트가 나타나므로, 펫이 스스로 무언가를 승인할 수는 없습니다.

3. SubagentStart / SubagentStop이 존재합니다. 저는 이를 제가 가장 좋아하는 기능에 사용했습니다. 서브에이전트(subagents)가 Craby 아래에서 아기 게로 부화하는 것입니다. 서브에이전트가 실행되는 동안 아기 게들은 바쁘게 움직이고, 작업이 끝나면 작은 지팡이를 든 채 은퇴하며 반짝임 속으로 사라집니다(실패할 경우 회색 연기와 낮은 쿵 소리가 납니다). 서브에이전트의 가시성(visibility)을 이런 방식으로 구현한 것은 어디에서도 본 적이 없으며, 훅 덕분에 매우 간단하게 만들 수 있었습니다.

4. 한 가지 솔직한 한계점: AskUserQuestion(객관식 질문)은 훅에 의해 가로챌 수 없습니다. 유도(Elicitation) 이벤트는 MCP 전용이기 때문입니다. 저의 해결책은 Claude가 먼저 펫의 HTTP API를 통해 질문하도록 하고, 그렇지 못할 경우 일반적인 흐름으로 넘어가는 CLAUDE.md 컨벤션을 사용하는 것입니다.

또한 다음과 같은 기능들도 포함되어 있습니다: 멀티 세션 스코어보드 (multi-session scoreboard), 일일 통계/레벨 (daily stats/levels), 트랜스크립트 (transcript)에서 로컬로 추출한 턴 요약 (turn summaries), 커스텀 스프라이트 팩 (custom sprite packs, 스프라이트는 단순한 텍스트 그리드 형태임), CLI, 그리고 자리를 비웠을 때의 ntfy 알림 (ntfy alerts). 재미있는 메타 정보: 서브에이전트 (subagent) 기능에 대한 문서는 서브에이전트들이 작성했으며, 그 과정에서 그들의 아기 게(baby crabs)들이 제 화면 위를 뛰어다녔습니다. 코드: https://github.com/duperez/crab-companion 라이브 데모가 포함된 사이트: https://duperez.github.io/crab-companion/ 훅 (hook) 설정에 관한 질문은 기꺼이 답변해 드리겠습니다. — 새로운 스프라이트 팩을 포함한 PR (Pull Request)은 언제든 환영합니다. 🦀 https://i.redd.it/142wmuqgfneh1.gif /u/PenteP 님이 제출함 [link] [comments]