notes

Desktop Pet — Codex 펫을 Cursor·Claude까지

2026-09-29수정 2026-09-296 min read

Git 프로젝트 옆에 앉아, Cursor·Claude와 함께 일하는 투명 데스크톱 캐릭터 desktop-pet.

Kim mr.

프론트엔드 · 기술 블로그

저장소: https://github.com/cpt4567/desktop-pet

앱·MCP 이름: desktop-pet

캐릭터: 모니빼기(모니터 얼굴의 보라색 개발 친구)

앱 아이콘 — 픽셀 모니터 + 시안·보라 네온

왜 만들었나

Codex 쪽에는 이미 “옆에 앉아 있는 펫” 경험이 있었습니다.

그걸 한 플랫폼에만 묶지 않고, Cursor·Claude(그리고 작업용 Codex CLI)처럼 여러 LLM과 함께 쓸 수 있는 데스크톱 펫으로 만들고 싶어서 이 프로젝트를 시작했습니다.

목표는 단순합니다.

Git 프로젝트 옆에 투명 창으로 앉아 있고
Cursor / Claude 등과 함께 일하며
에디터에서 작업 중일 때도 MCP로 상태가 실시간으로 따라오게 한다

설치·모듈·환경 변수 같은 세부는 저장소 README를 SSOT로 두었습니다.

→ https://github.com/cpt4567/desktop-pet

한 줄로

Git 프로젝트 옆에 앉아, Cursor·Claude와 함께 일하는 투명 데스크톱 캐릭터.

프레임리스 창 · Hatch Pet v2 스프라이트 · MCP 활동 연동 · 대화(세션) 단위 LLM 선택 · 명령 실행까지 한 앱에 묶었습니다.

OS 표시 이름은 「데스크톱 앱」, 앱/MCP 서버 이름은 desktop-pet 입니다.

원리는 이렇게 된다

1) 화면 위에는 “펫 + 얇은 UI”

Electron 프레임리스·투명 창에 모니빼기 스프라이트가 떠 있습니다.
상태줄(예: 모니빼기 · 함께 일할 준비 완료 / game · master), 프로젝트 카드, 설정, 툴바가 다크 반투명 패널로 붙습니다.
UI 톤: 다크 패널(#222124 계열) + 보라 액센트 #ba96ed.

2) 작업은 “프로젝트 + 대화(세션)”

로컬 Git 폴더를 연결하면 브랜치·변경 파일을 함께 봅니다.
Cursor 사이드바처럼 프로젝트별 작업 대화 목록을 두고, 대화마다 LLM·모델·모드·입력 초안·마지막 결과를 유지합니다.
「함께 작업하기」에서 명령을 보내면, 그 대화의 provider에 따라 한 번의 명령이 나갑니다.
Cursor → @cursor/sdk (CURSOR_API_KEY)
Claude → Claude Code CLI
Codex → Codex CLI (로그인된 CLI; 새 대화 기본 선택 UI에는 없음)
Cursor일 때만 모드(자동/디자인/로직)와 이미지 첨부(최대 4장)를 씁니다.

3) 에디터와는 MCP로 이어진다

에디터에 MCP 서버 desktop-pet 을 붙이면:

장시간 작업할 때는 대략 60초마다 working을 갱신해 주면, 펫 모션·상태 점이 실제 작업과 맞춰집니다. (패턴 세부는 README)

4) 에이전트 연결(MCP)과 기본 LLM

에이전트 연결 패널에서 MCP를 붙이는 대상은 Cursor · Claude입니다. (Codex MCP 연결 행은 현재 없음 — Codex는 세션 작업용 CLI로만)

Cursor: MCP 설치 딥링크 + 설정 복사
Claude Code: CLI mcp add 등록
연결 순서를 기억하고, 가장 먼저 연결된 에이전트가 기본 작업 LLM (끊기면 순서대로 폴백)
「새 대화 LLM 팝오버」가 켜져 있으면 ＋ 시 Cursor/Claude를 고르고, 꺼져 있으면 위 기본 LLM으로 바로 새 세션

에디터에서 코딩할 때도 펫이 옆에 있고, 작업 상태는 pet_report_activity로 전달됩니다.

5) 프로세스 구조

flowchart TB
  R["renderer<br>투명 창 · 스프라이트 · 패널"]
  M["electron/main<br>companion · workSessions · cursorAgent"]
  A["Cursor SDK · Claude CLI · Codex CLI"]
  E["에디터<br>Cursor IDE / Claude Code"]
  P["pet-mcp.cjs"]
  R <-->|"IPC petApi"| M
  M -->|"spawn / SDK<br>함께 작업하기"| A
  E <-->|"stdio MCP"| P
  P -->|"activity 파일"| M

보안: 렌더러는 contextIsolation + sandbox, preload로 window.petApi만 노출.

MCP stdout은 JSON-RPC 전용, Git 도구는 읽기 전용·프로젝트 스코프.

데이터는 userData의 companion.json, work-sessions.json, pet-library.json, mcp-activity/*.json 등에 저장됩니다.

형식은 이렇다 (보이는 모양)

독/설치 아이콘 — 픽셀 모니터 캐릭터 + 시안·보라 네온 프레임. UI 보라 톤과 맞춤.
데스크톱 위 펫 — 모니빼기: 모니터 얼굴 + 보라 슬라임 바디(Hatch Pet v2 아틀라스). idle / working / waiting / wave 등 모션, 포인터 시선.

나의 펫에서 지금 옆에 둘 캐릭터를 고른다. 모니빼기는 기본 펫으로 들어가 있고, 「+ 나만의 펫」으로 라이브러리에 추가할 수 있다. 카드 아래 상태 배지에는 초록 점 + 이름 + “함께 일할 준비 완료” + 프로젝트 · 브랜치가 붙는다. 선택값은 pet-library.json에 남는다.