# Show GN: claudlet — Claude Code의 작업 상태를 시각화하는 픽셀 데스크톱 펫

> Clean Markdown view of GeekNews topic #31607. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=31607](https://news.hada.io/topic?id=31607)
- GeekNews Markdown: [https://news.hada.io/topic/31607.md](https://news.hada.io/topic/31607.md)
- Type: show
- Author: [ghksqkdwod](https://news.hada.io/@ghksqkdwod)
- Published: 2026-07-20T10:32:16+09:00
- Updated: 2026-07-20T10:32:16+09:00
- Original source: [github.com/YeeDochi](https://github.com/YeeDochi/Claudlet)
- Points: 3
- Comments: 0

## Topic Body

터미널 스크롤만 보며 'Claude가 지금 코드를 짜는 중인지, 파일을 뒤지는지, 내 응답을 기다리는지' 답답했던 경험 있으신가요?  
**claudlet**은 Claude Code의 현재 작업 상태를 직관적이고 귀엽게 보여주는 반응형 데스크톱 픽셀 펫입니다.  
  
##### 주요 기능  
* **실시간 상태 동기화:** 타이핑, 파일 읽기, 생각 중, 대기 등 Claude의 훅(Hook)을 캐치해 펫의 행동과 표정으로 즉시 보여줍니다.  
* **서브에이전트 시각화:** Claude가 서브에이전트를 호출하면, 안전모를 쓴 꼬마 동료가 나타나 졸졸 따라다니며 작업을 흉내 냅니다.  
* **창 상호작용 & 물리 엔진:** 할 일이 없으면 활성화된 창틀을 걸어 다닙니다. 마우스로 집어 던지면 포물선을 그리며 날아가고, 창 가장자리를 밟고 점프도 합니다.  
* **세션별 1:1 매칭:** 여러 세션을 띄우면 펫도 여러 마리가 등장합니다. 펫을 클릭하면 해당 Claude 세션의 터미널 창을 맨 앞으로 가져옵니다.  
  
##### 기술적 특징 (How it works)  
* **Zero-Asset (순수 코드 렌더링):** PNG 같은 외부 이미지 리소스가 전혀 없습니다. 모든 아트워크와 애니메이션(바운스, 스쿼시&스트레치 등)을 `QPainter`를 이용해 픽셀 단위로 직접 코드로 그렸습니다. 덕분에 라이선스 부담 없이 자유롭게 활용 및 수정이 가능합니다.  
* **안전한 논블로킹 아키텍처:** `Hook → TCP 소켓 → 펫 프로세스` 구조입니다. 펫이 꺼져있거나 에러가 나도 조용히 연결만 실패할 뿐, Claude Code의 본래 작업은 절대 방해하지 않습니다 (불변식 보장).  
* **크로스 플랫폼 네이티브 창 인식:** Windows(Win32), macOS(Quartz), Linux(KDE Plasma/XWayland) 환경에서 OS별 네이티브 API를 호출해 창의 위치를 정확히 추적하고 올라탑니다.  
  
##### 예시  
![데모 1](https://raw.githubusercontent.com/YeeDochi/Claudlet/master/docs/demo-3.gif)  
![데모 2](https://raw.githubusercontent.com/YeeDochi/Claudlet/master/docs/companion_demo.gif)  
![데모 3](https://raw.githubusercontent.com/YeeDochi/Claudlet/master/docs/companion.gif)  
  
##### 설치 및 실행  
```bash  
pipx install claudlet && claudlet-install  
```  
* 명령어 한 번으로 훅과 `/claudlet` 스킬이 멱등(Idempotent)으로 자동 등록됩니다.  
* 이후 새로운 Claude Code 세션을 열면 펫이 자동으로 등장합니다.  
  
---

## Comments



_No public comments on this page._