Codex Mac App 가이드(3) : Codex App 펫(Pets) 사용 방법 : 백그라운드 AI 에이전트 실시간 모니터링, 나만의 픽셀 아바타 만들기

안녕하세요! 갓대희 입니다.

Codex 에이전트에게 중장기 작업을 맡기면 늘 마주하는 문제가 있다. 백그라운드에서 연산 중인 에이전트가 지금 승인을 기다리는지, 이미 끝났는지, 아직 갈 길이 먼지 — 매번 Codex 창을 열어 확인해야 했다.

OpenAI가 이 불편함을 없앴다. 화면 구석에 떠다니는 작은 픽셀 캐릭터, Codex 펫(Pets)이 에이전트의 실시간 상태를 알려주기 시작한 것이다.

 

Codex 펫이란 백그라운드 에이전트의 작업 상태를 화면 위에 떠서 알려주는 선택형 애니메이션 캐릭터다(공식 명칭: "Optional animated companions"). 에이전트 상태를 색상·아이콘으로 구분하고, 말풍선을 클릭하면 Codex 본체 없이도 바로 답장을 보낼 수 있다. 기본 8종을 고르거나, /hatch 명령으로 나만의 펫을 만들거나, codex-pets.net 커뮤니티 펫을 가져올 수도 있다.

본 가이드는 2026년 5월 29일 발표 자료를 바탕으로 작성되었다.
공식 출처: Codex App 공식 개발자 가이드, codex-pets.net 커뮤니티 펫 아카이브. 커뮤니티 갤러리 수치 정보는 실시간 갱신되므로 최신 공식 페이지와 대조하길 권한다.

Codex Mac App 실무 정복 시리즈

Part 1: Codex App 기초 가이드 Part 2: Codex App 원격 연동 가이드Part 3: Codex App 펫(Pets) 활용 가이드 — 현재 글

목차

1. 펫의 탄생 배경 — 어떤 문제를 해결해 주는가
2. 펫 활성화 옵션 — /pet 명령어와 시스템 단축키
3. 기본 장착 가능한 8종 픽셀 펫 라인업
4. 에이전트 3색 상태 변화 — Running · Waiting · Ready
5. 인터랙티브 인라인 답변 — 양방향 소통 채널
6. /hatch 스킬 활용 — 세상에 단 하나뿐인 커스텀 펫 만들기
7. 전 세계 펫 아카이브 — codex-pets.net 갤러리 활용
8. 커뮤니티 펫 설치 방법
9. 이용자 주의사항 — 동명 오픈소스 프로젝트 분리 및 저작권 가이드
10. 요약 정리 — 펫 활용이 유용한 상황과 소환 해제 팁

 

1. 펫이란 무엇인가 — 왜 만들어졌나

기존 Codex 자율 에이전트의 아쉬운 점은 백그라운드 실행 중 진행 상황을 직관적으로 확인하기 어렵다는 것이었다.

Codex 본체가 트레이로 내려가 있거나 다른 IDE가 전면을 덮고 있어도, 픽셀 아바타는 항상 화면 최상단에 상주한다.

에이전트가 사람의 판단을 요구하는 순간 앱을 직접 찾아볼 필요 없이 펫이 그 자리에서 신호를 보낸다.

 

2. 펫 활성화 방법

다음과 같은 경로에서 펫을 활성화 있다. : 설정(Settings) > 모양(Appearance) > 펫(Pets)

 

1) 설정

2)  모양 클릭 > 우측 패널의 가장 하단으로 가보면 "펫" 메뉴가 보일 것 이다. 활성화 해보자.

 

3) 원하는 펫을 "선택" 클릭 > "펫 깨우기" 클릭(나의 경우 활성화 되어있어서 펫 숨기기로 캡쳐 되어있다.)

 

4) 처음 소환하면 기본 픽셀 캐릭터가 화면 우측 모서리에 나타난다.

 

5) 드래그 앤 드롭을 지원하므로, 시야를 방해하지 않는 구석이나 듀얼 모니터 한편으로 밀어두고 쓰면 된다.

 

6) 기본 내장 8종을 선택하거나, 커스텀 아바타를 로드할 수 있다.

 

3. 기본 제공 8종 펫 소개

설치 직후 선택할 수 있는 기본 펫은 총 8종이며, 화면 점유율을 최소화한 레트로 픽셀 아트 스타일로 그려져 있다.

 

기본 제공되는 모든 펫은 아래 3가지 조작을 지원한다.

인터랙션	동작 결과
드래그 이동	마우스 드래그로 화면 어느 구석이든 끌어다 배치 가능
메시지 버블	에이전트가 탐색·연산 중인 정보를 말풍선으로 표시
버블 클릭	메시지 버블 클릭 시 그 자리에서 에이전트와 지시를 주고받는 미니 입력창 팝업

 

4. 에이전트 상태 3종 — Running · Waiting · Ready

핵심은 3색 상태 지표다. 아이콘 색과 형태만 봐도 모델의 현재 상태를 바로 알 수 있다.

상태	시각적 표현	의미	권장 조치
Running	⚙️ 연산 중 애니메이션 + 말풍선	에이전트가 탐색하거나 코드를 수정하는 중	완성 전까지 다른 작업에 집중
Waiting for input	🕓 시계 아이콘 + 말풍선 대기	에이전트가 승인이나 추가 지시를 기다리며 멈춤	펫을 탭해 인라인 입력창에서 빠르게 승인
Ready for review	✅ 초록 체크 서클	목표 구현 완료, 코드 변경(Diff) 리뷰 대기	현재 작업 마무리 후 본체로 복귀해 리뷰 진행

갑자기 다른 펫으로 변경되었는데, 내가 만든 커스텀 펫 이다. (이후 섹션에서 만드는법은 설명 예정 이다.)

 

ex) Running

 - 프로젝트 목록에서의 표시 방식 : 인디케이터가 돌아가는 모습

 - 펫도 동일한 인디케이터가 돌아가고 있는 모습

 

ex) Waiting for input

 - 프로젝트 목록에서의 표시 방식 : 승인 대기 중

 - 펫 : 시계 아이콘

 - 실제 세션 화면에서의 권한 승인 대기 상태

 

ex) 여러 작업을 병렬로 동작하는 모습

 

🕓 빨간 시계가 보이면 승인이나 추가 입력이 필요하다는 신호다.

 

ex) Ready for review

 - 작업이 끝나면(목표 구현 완료, 코드 변경(Diff) 리뷰 대기 등) ✅ 초록 체크 서클 로 상태를 알려준다.

 

이 몇가지 표기만 눈에 익히면 Codex 창을 전환할 타이밍이 자연스럽게 잡힐 것 이다.

 

5. 인터랙티브 답변 기능 — 양방향 소통 채널

플로팅 펫은 진행 상태만 보여주는 단방향 위젯이 아니다.

메시지 버블을 클릭하면 그 자리에서 인라인 텍스트 패널이 열리고, 화면 포커스를 바꾸지 않고도 에이전트에게 피드백을 전달할 수 있다.

 

ex) 🕓 빨간 시계 알림 또는 Codex가 작업 중인 도중에도 갑자기 요청할 내용이 있다면 펫 메시지 버블에 바우스 오버레이 해보자. 

 - "답장" 이라는 버튼이 활성화 되니 클릭해보자. 

 - AI로 프롬프트를 보낼 수 있는 경량 텍스트 패널이 열린다.  

 

처음에는 좁은 말풍선에 짧은 명령을 타이핑하는 게 어색했지만, 익숙해지면 🕓 빨간불이 들어왔을 때 승인 신호를 보내고 코딩으로 돌아오는 리듬이 자연스러워졌다.

긴 설계 지침은 본체 창에서, 짧은 확인과 분기 수락은 펫 버블에서 처리하면 된다.

 

6. /hatch — 나만의 펫 만들기

기본 8종 스킨이 마음에 들지 않거나, 나만의 브랜드 로고나 반려동물 모습을 화면에 띄우고 싶다면 Codex 입력창에 /hatch 명령을 입력하면 된다. 이미지를 드롭하거나 원하는 모습을 텍스트로 묘사하면 Hatch 스킬이 픽셀 스프라이트 펫을 만들어 준다.

입력 방식	세부 방법	출력 결과
이미지 업로드	/hatch 실행 후 로컬 파일 첨부	이미지를 분석해 9가지 동작의 픽셀 애니메이션으로 변환
텍스트 묘사	/hatch 후 원하는 아바타 특징을 텍스트로 입력	텍스트 프롬프트를 기반으로 AI가 픽셀 스프라이트 생성

스프라이트 프레임 생성에 약 30분이 걸리므로, /hatch 명령을 실행해 두고 다른 작업을 진행하는 게 낫다. 완성되면 자동으로 설정(Settings) > 모양(Appearance) > 펫(Pets) 목록에 등록된다.

 

ex) 난 이미지도 주고, 텍스트로도 묘사 하여 생성 요청 하였다.

 - /hatch 펫을 만들고 싶어. 귀멸의 칼날 아카자 스타일의 펫을 만들어줘

  ( 사실 개인사용시 문제가 없곘지만, 블로그에 올린땐 이런 케릭터를 사용하는게 불편하신 분들이 계셔 블러처리 )

 - 42분이나 걸렸다.

    ( 중간 사고과정을 보면 오래 걸릴만 한 작업으로 보인다.. 중간 사고 과정을 공유 )

 

7. 커뮤니티 갤러리 — codex-pets.net

기본 duck, flame 스킨에서 벗어나고 싶다면 codex-pets.net 갤러리를 한번 둘러보자.

 

전 세계 빌더들이 올린 다양한 테마 펫이 등록돼 있다.

이 사이트는 portons/codex-pet-share 오픈소스 커뮤니티가 MIT 라이선스 기반으로 자발적으로 운영하고 있다고 한다.

검색/정렬 필터	지원 사양
정렬 옵션	Newest · Liked · Viewed · Discussed · Random
종류별 카테고리(kind)	Object(사물) · Animal(동물) · Person(인물) · Creature(환상 정령)
태그 검색	커뮤니티가 부여한 키워드로 픽셀 스타일 검색 가능

마음에 드는 펫을 찾았다면 카드에 표시된 펫 ID를 메모해 두자. 바로 설치 명령어로 활용할 수 있다.

 

8. 커뮤니티 펫 설치 방법

갤러리에서 원하는 펫을 골랐다면, 아래 2가지 방법 중 로컬 환경에 맞는 방식을 선택하자.

① npx 명령어 한 줄 설치 (가장 간단)

npx codex-pets add <펫ID>
# 예시
npx codex-pets add scarf-cat-asset

Node.js가 설치된 환경이라면 터미널에 한 줄만 붙여 넣으면 끝난다. 갤러리 펫 카드 하단에 표시된 명령어를 그대로 복사해 실행하면 된다.

 

ex) 

 - npx codex-pets add guga

 

② ZIP 패키지 다운로드 후 수동 해제

# macOS / Linux 예시
mkdir -p "$HOME/.codex/pets/scarf-cat-asset"
unzip ~/Downloads/scarf-cat-asset.codex-pet.zip \
  -d "$HOME/.codex/pets/scarf-cat-asset"

브라우저로 ZIP 파일을 내려받아 OS별 펫 설치 경로에 폴더째 압축을 푸는 방법이다. Node.js 환경이 없거나 파일 내용을 직접 확인하고 싶을 때 쓰기 좋다. (macOS: $HOME/.codex/pets/ · Windows: %USERPROFILE%\.codex\pets\)

 

9. 주의사항 — 유사 이름 별개 프로젝트·저작권

아래 외부 프로젝트들은 Codex 공식 펫과 연동되지 않는다

검색하다 보면 이름이 비슷한 별개의 앱들이 함께 노출된다. 아래 3가지는 공식 Codex 펫과 무관한 독립 서비스다.

• codingpets.com — 전혀 다른 목적의 유료 솔루션
• codexpets.app — 이름만 비슷한 별개 서비스
• codexpets/codex-pets (GitHub 오픈소스) — Codex를 넘어 Claude Code, Cursor 등 범용 IDE를 대상으로 한 별도 위젯형 데스크탑 마스코트

CLI 명령어 구조, 저장 디렉토리, 기능 연동 방식이 완전히 다르므로 혼동하지 않도록 주의하자.

커뮤니티 펫 사용 전 확인할 사항

• 출처 확인: codex-pets.net 아카이브는 전 세계 빌더들의 창작물 모음이다. OpenAI가 코드 감수나 보안 검토를 거친 자산이 아님을 염두에 두자.
• 팬아트 저작권 주의: 유명 캐릭터를 픽셀로 오마주한 2차 창작물이 섞여 있다. 기업 프레젠테이션이나 기술 방송에 펫을 띄울 때는 라이선스 리스크가 없는지 확인하는 편이 안전하다.
• ZIP 내용물 점검: 이미지와 정적 JSON으로만 구성돼 악성 코드 위험은 낮지만, 수동 해제 시 엉뚱한 스크립트 파일이 없는지 확인하는 습관을 들이자.

 

10. 정리 — 펫을 쓰면 좋은 상황, 끄는 법

펫은 반드시 켜야 하는 기능이 아니다. 비활성화해도 자율 에이전트의 연산 능력이나 프롬프트 처리에는 아무 영향이 없다. 

코딩 상황	권장 여부	이유
에이전트에게 무거운 프레임워크 리팩터링을 맡긴 긴 연산 주기	켜기	본체 앱 창을 오갈 필요가 없어진다
다중 병렬 서브에이전트를 동시에 실행 중인 복합 작업	켜기	어느 에이전트에서 문제가 생겼는지 주변시로 바로 파악 가능
30분 이내에 끝낼 가벼운 단기 작업	선택	본체 창에서 바로 결과를 확인하면 되므로 필요성이 낮다
클라이언트 대상 화면 공유, 기술 세미나 라이브 코딩	끄기	화면 구석의 픽셀 캐릭터로 청중 시선이 분산된다
깊은 집중이 필요한 딥 코딩 상황	끄기	시각적 움직임이 방해가 될 수 있다

지금 바로 해볼 수 있는 체크리스트

• /pet 명령으로 기본 펫을 띄운 뒤, 에이전트에게 작업을 맡기고 🕓/✅ 색 변화를 직접 확인해 본다.
• Settings > Appearance > Pets에서 내장 8종을 둘러보고 마음에 드는 스킨을 고른다. 더 다양한 스킨은 codex-pets.net에서 npx codex-pets add <펫ID> 한 줄로 설치 가능하다.
• 나만의 캐릭터를 원한다면 /hatch로 AI가 생성하는 커스텀 펫을 만들어 본다(약 30분 소요).

가이드 시리즈 다른 글

Codex Mac App 시리즈의 다른 포스트들도 함께 읽어보자.
• Part 1: Mac App 완전 정복 가이드 — 빌드업·초기 세팅·승인 옵션
• Part 2: 다중 디바이스 연결 가이드 — 원격 제어 및 모바일 연동

최초 작성일: 2026년 5월 29일

실측 대상 릴리스 버전 정보: Codex Mac App (2026년 5월 빌드 기준), codex-pets.net (2026-05-27 DB 기준)

공식 기술 개발자 아카이브

• Codex App 공식 개발자 가이드
• Codex App 설정 지원 탭
• codex-pets.net 커뮤니티 갤러리
• portons/codex-pet-share GitHub
• Engadget — OpenAI introduces AI-generated pets for its Codex app
• Digital Trends — OpenAI's Codex now has a tiny AI pet