나의 반려 클로디(Claudy)!

🐾 GitHub : https://github.com/ESeungJun/claude-bouncer

안녕하세요 ! 안드로이드 개발하고 있는 이승준입니다.

요즘 Claude Code를 터미널 여러 개에 띄워놓고 일하는 경우가 많은데요
다른 일 하다 보면 "끝났나?", "권한 요청 떠 있는 거 아냐?" 하면서 계속 창을 왔다 갔다 하게 되더라고요.

그래서 바탕화면에 작은 도트 클로드를 하나 띄워봤어요.
평소엔 화면을 돌아다니고 낮잠도 자다가
세션이 끝나거나 나를 기다리면 커서 앞으로 달려와서
어느 프로젝트, 어느 브랜치, 어느 터미널 탭에서 불렀는지 카드로 알려줍니다.

사실 처음 만든 건 올해 4월이었는데
그때는 화면 구석에서 통통 튀기만 하는 단순한 알림이었어요.
이번에 다시 꺼내서 같이 놀 수 있는 펫으로 거의 새로 만들었습니다.

이번에도 구현은 거의 Claude Code가 했고요
이 글은 그 과정에서 했던 결정이랑 그 이유를 정리한 글입니다.

---

먼저 결과물부터

• 알림 카드 - 작업 완료 · 권한 요청 · 입력 대기를 구분하고, 프로젝트 · 브랜치 · 내가 보낸 요청 · 결과 요약 · 걸린 시간 · 터미널 탭까지 보여줘요
• 원클릭 이동 - 카드를 누르면 그 세션이 있는 터미널 탭으로 바로 이동해요
• 같이 노는 펫 - 쓰다듬기, 밥 주기, 공놀이, 미니게임 2개, 배고픔 · 재미 · 기운과 레벨
• 나만의 캐릭터 - 사진을 넣으면 나를 닮은 도트 캐릭터로 바꿔 입어요
• claude.ai 웹도 - 브라우저 확장을 깔면 웹 채팅 답변이 끝나도 알려줘요

macOS랑 Windows 둘 다 되고, MIT 라이선스로 열어뒀어요.

숫자로 보면 이 정도예요.

• v2 첫 커밋 하나에 50개 파일, 4,700줄 정도 추가
• 이후 PR 13개 (claude.ai 확장, 나만의 캐릭터, 코드 리뷰 수정, 설치 파일 자동 빌드 등)
• 단위 테스트 37개

---

v1에서 뭐가 달라졌나

v1은 진짜 "알림" 하나만 하는 앱이었어요.
세션이 끝나면 화면 오른쪽 아래에서 펫이 통통 튀고, 누르면 터미널로 가는 정도였죠.

근데 솔직히 그래픽이 별로 귀엽지 않았고
기능 자체에도 버그가 꽤 많았어요,,
조금씩 고쳐서 쓰기보다는 아예 새로 만드는 게 낫겠다 싶었습니다.

그래서 v2는 두 가지를 잡고 시작했어요.

• 그래픽은 Higgsfield로 캐릭터 컨셉부터 다시 잡아서 리뉴얼하기
• 기능은 알림만 하는 앱이 아니라, 좀 더 캐주얼하면서 같이 놀기 재밌는 펫으로 만들기

알림도 그냥 튀는 것 말고, 누가 불렀는지 카드 한 장으로 끝나게 바꿨고요.

---

1. 누가 불렀는지 확실하게

카드에는 생각나는 정보는 다 넣었어요.
작업 완료인지 권한 요청인지, 어느 프로젝트의 어느 브랜치인지, 내가 마지막에 뭘 시켰는지, 결과가 뭔지까지요.

권한 · 입력 요청은 처리할 때까지 남긴다

• 작업 완료 알림은 잠깐 보여주고 들어가는데, 권한 요청이나 입력 대기는 펫이 옆에서 기다리면서 카드를 남겨둬요.
• 그 세션에 다시 입력하면 알아서 정리되고요.
• 잠깐 떴다 사라지면 놓쳤는지도 모르는 게 제일 곤란하더라고요.

카드를 누르면 정확한 탭으로

• iTerm2랑 macOS 터미널은 tty로 탭을 찾아가고, tmux는 pane까지 골라요.
• Orca 터미널은 AppleScript로 탭을 고를 방법이 없어서 앱만 앞으로 오고 끝이었어요.
• 훅에서 Orca가 넣어주는 패널 ID를 같이 보내고, 카드를 누르면 Orca CLI로 그 탭을 찾아서 전환하게 바꿨습니다.

패널에는 알림함이랑 열려 있는 세션 전체 현황(작업 중 · 응답 필요 · 끝남)도 있어요.
자리 비웠다 돌아오면 "자리 비운 사이 알림 3개 왔어 !" 하고 알려주기도 하고요.

---

2. 같이 노는 펫

펫은 화면 전체를 덮는 투명 창 위에서 움직여요.
대신 펫, 카드, 메뉴 위에서만 클릭을 받고 나머지는 전부 아래 앱으로 통과시켰어요.
화면 전체를 덮는 창이 클릭을 먹으면 그날로 지워버릴 것 같아서요,,

v2 그래픽은 Higgsfield로 캐릭터 컨셉 시트랑 앱 아이콘을 먼저 만들고
앱 속 스프라이트는 코드로 한 픽셀씩 찍었어요. (18×14 칸)
걷기, 폴짝, 낮잠, 냠냠, 어지러워하는 표정까지 다 코드예요.

놀 거리는 이 정도 넣었어요.

• 쓰다듬기 - 펫 위에서 마우스를 좌우로 문지르면 하트가 나와요
• 던지기 - 드래그해서 던지면 날아가는데, 세게 던지면 어지러워해요
• 밥 주기 - 쿠키를 들고 아무 데나 떨어뜨리면 달려와서 먹어요
• 미니게임 - 쿠키 받기(버그는 피하기)랑 술래잡기
• 돌보기 - 배고픔 · 재미 · 기운이 시간 따라 줄어서, 심심하면 먼저 와서 조르고 졸리면 자요

알림 앱인데 미니게임까지 넣은 건 좀 오버인가 싶긴 했는데
펫이 먼저 와서 놀아달라고 조르니까 결국 하게 되더라고요,,

---

3. 나만의 캐릭터

사진을 넣으면 나를 닮은 도트 캐릭터로 바꿔 입는 기능이에요.
이미지는 Higgsfield로 만들었는데 여기서 정한 게 몇 가지 있어요.

API 키 대신 계정으로 로그인

• 처음엔 Higgsfield API 키를 넣는 방식이었어요.
• 근데 키 발급부터 시키면 대부분 거기서 멈출 것 같더라고요.
• 그래서 Claude Code의 Higgsfield 커넥터랑 같은 MCP 연결로, 브라우저에서 로그인만 하면 되게 바꿨어요. (토큰은 OS 키체인으로 암호화해서 저장해요)

도트로 다시 찍기

• Higgsfield가 같은 캐릭터의 6컷(가만히 · 깜빡 · 걷기 2컷 · 점프 · 잠자기)을 한 장에 그려주면, 앱이 컷을 잘라서 애니메이션으로 써요.
• 처음엔 그냥 줄여서 썼더니 얼굴이 뭉개졌어요.
• 같은 색이 몇 칸씩 이어지는지 보고 원래 도트 크기를 찾은 다음, 칸마다 제일 많은 색을 고르되 눈 같은 어두운 디테일을 먼저 살리게 바꿨습니다.

사람 모양이 아니어도 된다

• 처음엔 사람 사진만 생각했는데, 반려동물이나 화분으로 만들어보고 싶을 것 같더라고요.
• 고양이는 네 발 고양이 그대로, 선인장은 화분째로, 동작도 몸에 맞게(앞발 내딛기 · 깡총 · 흔들흔들) 그리게 했어요.
• 대신 없는 특징은 지어내지 말라고 해뒀어요. 귀엽게 바꾸는 건 좋은데 안 닮으면 의미가 없으니까요.

계정이 없어도 바꿔 입을 수 있게

• Higgsfield 계정이 없으면 이 기능을 아예 못 쓰는 게 좀 아쉬웠어요.
• 그래서 고양이 · 강아지 · 주먹밥 기본 캐릭터 3종을 넣어서 바로 고를 수 있게 했어요.
• 고양이랑 강아지는 옆모습 걷기 4컷까지 있어서, 걸을 땐 진짜 네 발로 걸어가요.
• 그래도 내 캐릭터가 갖고 싶은 분은 패널에서 사진을 보내주시면 제가 직접 만들어서 메일로 보내드려요. (제가 Higgsfield 크레딧이 버티는 한,,)

참고로 시험 삼아 포켓몬 이미지를 넣어봤는데 "nsfw"로 거절당했어요. (아찔)
저작권 캐릭터는 콘텐츠 정책에 걸리는 거였고, 다행히 크레딧은 안 빠지더라고요.
"사진이 정책에 걸렸어요" 만 보면 뭐가 문제인지 모르니까, 내 사진이나 반려동물, 직접 그린 캐릭터로 해보라고 안내 문구를 바꿨습니다.

---

4. claude.ai 웹 채팅도

Claude Code는 훅이 있어서 알림 받기가 쉬운데
claude.ai 웹 채팅은 그런 게 없어서 작은 브라우저 확장을 하나 만들었어요.

• claude.ai 탭에서 답변이 시작되고 끝나는 걸 감지해서 앱에 알려줘요.
• 화면 문구 대신 답변 요소에 붙는 속성으로 판단해서, 언어 설정이 달라도 동작해요.
• 이미 그 탭을 보고 있을 때 끝났으면 카드를 안 띄워요. 보고 있는데 알려주면 그게 방해라서요.
• 확장은 claude.ai 페이지만 읽고, 내 컴퓨터(127.0.0.1)하고만 통신해요.

---

5. 설치도 쉽게

처음엔 저장소를 받아서 start.command를 더블클릭하는 방식이었는데
Node.js가 깔려 있어야 하고, 훅 스크립트도 Node로 돌아서 개발자가 아니면 쓰기가 어려웠어요.

• 설치형 앱은 앱 실행 파일 자체를 Node처럼 돌려서(ELECTRON_RUN_AS_NODE=1) 훅을 실행하게 했어요. Node.js가 없어도 알림을 받을 수 있어요.
• v* 태그를 올리면 GitHub Actions가 macOS(dmg · zip, Apple Silicon · Intel)랑 Windows(exe) 설치 파일을 빌드해서 릴리스 초안에 올려줘요.
• 아직 코드 서명은 없어서 처음 실행할 땐 우클릭 → 열기를 한 번 해야 해요. 서명 인증서까지 사기엔 아직 펫 밥값도 못 벌어서요,,

---

삽질 몇 가지

1. 훅 설치하다가 남의 훅을 지움

• 앱이 켜질 때 ~/.claude/settings.json에 훅 4개를 등록하는데, 지울 때 send-notify.js가 들어간 명령이면 다 지우고 있었어요.
• 같은 그룹에 사용자가 넣어둔 다른 명령까지 같이 날아가는 구조였고요,,
• claude-bouncer 경로를 정확히 매칭해서 우리 명령만 빼도록 고쳤습니다.

2. 느린 맥에서 빈 알림이 옴

• 훅 스크립트가 80ms 안에 입력이 안 들어오면 그냥 빈 알림을 보내고 있었어요.
• 그래서 느린 환경에서는 빈 카드가 뜨고 진짜 알림은 버려졌어요.
• 파이프로 들어오는 입력은 끝까지 기다리게 바꿨습니다.

3. 주먹밥의 밥이 투명해짐

• 기본 캐릭터를 넣었더니 주먹밥의 밥이랑 강아지 흰 털이 배경처럼 투명하게 빠져서 뒤가 비쳐 보였어요.
• 생성된 그림의 흰 배경을 지우면서 캐릭터 안의 흰색까지 같이 지우고 있었던 거예요.
• 그림 바깥과 이어진 흰색만 배경으로 보고, 외곽선 안쪽 흰색은 캐릭터 색으로 남기게 고쳤습니다.
• 겸사겸사 걷기 2컷이 꼬리 위치까지 달라서 깜빡여 보이던 것도, 가만히 컷을 살짝 기울이면서 뒤뚱뒤뚱 걷게 바꿨어요.
• 근데 이번엔 고양이랑 강아지가 앉은 채로 미끄러지면서 이동하는 것처럼 보이더라고요,,
• 결국 그림을 만들 때 옆모습 걷기 4컷을 같이 그리게 바꾸고, 기본 캐릭터도 다시 만들었습니다.

4. 홍보 영상이 커밋에 딸려 올라감

• 작업 폴더에 둔 홍보 영상이 git add -A에 같이 쓸려서 PR에 올라갔어요.
• 실수인 줄 알고 추적 해제 PR까지 머지했는데, 생각해보니 일부러 넣으려던 거였어요,,
• 그래서 그걸 다시 되돌리는 PR을 또 올렸습니다. (PR 두 개 순삭)

---

홍보 영상도 만들었다

33초짜리 홍보 영상도 하나 만들었어요.
이건 claude.ai 웹에서 바운서 저장소 README를 넘겨주고 모션그래픽으로 만들어달라고 했어요.
터미널 여러 개 앞에서 "끝났나?" 하는 장면으로 시작해서, 카드 · 쿠키 · 미니게임 · 나만의 캐릭터 순서로 보여줘요.

글에 넣은 GIF 두 개도 이 영상에서 잘라낸 거예요.

🎬 영상 : https://github.com/ESeungJun/claude-bouncer/blob/master/claude-bouncer-ad-silent.mp4

---

해보고 나서

앞에서 말한 것처럼 구현은 거의 Claude Code가 했는데요
돌아보니 이번에도 제가 한 건 대부분 "방향성 제시와 왜 그렇게 해야 하는지에 대한 결정" 이었던 것 같아요.

처음 잡은 목표는 다섯 가지였어요.

• 귀엽고, 캐주얼하게 같이 놀고 싶은 펫
• 누가 불렀는지 카드 한 장으로 확실하게
• 일하는 중에 방해가 되지 않게
• 개발자가 아니어도 쉽게 설치하고 꾸밀 수 있게
• 남의 컴퓨터 설정은 건드리지 않게

중간중간 갈림길마다 이 기준으로 정했습니다.

제일 신경 쓴 건 "방해하지 않기" 쪽이었어요.
바탕화면에 항상 떠 있는 앱이라, 조금만 거슬려도 바로 꺼버리게 되거든요.
그래서 클릭을 통과시키고, 이미 보고 있는 건 안 알려주고, 방해 금지 모드까지 넣었어요.

알림 하나 받자고 만든 앱이 펫이 되고 게임까지 됐는데
덕분에 터미널을 왔다 갔다 하는 일은 확실히 줄었습니다.

혹시 써보시고 재밌으면 스타 하나 눌러주세요 ⭐

🐾 GitHub : https://github.com/ESeungJun/claude-bouncer
💼 LinkedIn : https://www.linkedin.com/in/승준-이-53707a328/