치이카와 데스크톱 펫 설치 및 Codex 적용 가이드

목차

1. 치이카와 데스크톱 펫이란
2. 지원 캐릭터 11종 및 동작 상태 규격
3. 터미널 한 줄로 끝내는 자동 설치 방법
4. 원하는 캐릭터만 골라 설치하는 팁
5. 직접 내려받아 수동으로 등록하기
6. Codex 데스크톱 앱에서 펫 불러오기
7. 직접 적용해 본 경험과 반응형 동작 테스트
8. 자주 겪는 문제와 해결 방법
9. 용어 정리

치이카와 데스크톱 펫이란

치이카와 데스크톱 펫은 오픈AI 코덱스(OpenAI Codex) 앱에서 함께 일하는 도트 그래픽 동반자입니다.

인기 애니메이션 ’먼가 작고 귀여운 녀석(이하 먼작귀)’의 친구들이 개발 화면 창가에 상주합니다. 개발자가 코드를 작성하거나 에이전트가 작업을 수행할 때 실시간으로 상태를 보여줍니다.

기존의 단순 화면 장식 프로그램과 달리 개발 환경의 진행 상황과 연동됩니다. 코덱스 에이전트가 빌드를 돌리거나 테스트를 검토할 때 표정과 행동이 즉각 달라집니다. 관련된 에이전트 작업 공간 구성은 Codex 데스크톱 및 에이전트 워크플로 가이드에서 함께 확인하실 수 있습니다.

지원 캐릭터 11종 및 동작 상태 규격

먼작귀 세계관에 등장하는 주요 인물 11명이 코덱스 펫 버전 2(Codex Pet v2) 규격으로 담겨 있습니다.

스프라이트 시트(Sprite Sheet, 여러 프레임을 모은 하나의 이미지 파일)는 8열 11행 그리드로 제작되었습니다. 투명 배경의 1536 × 2288 해상도이며, 한 칸의 크기는 192 × 208 픽셀입니다.

각 캐릭터는 코덱스의 실행 상태에 맞춰 9가지 기본 상태를 연출합니다. 추가로 9행과 10행에는 마우스 커서를 바라보는 16방향 시선 각도가 구현되어 있습니다.

• idle (쉬기, 6프레임): 작업이 없을 때 편안히 숨 쉬는 대기 동작
• running-right (우측 달리기, 8프레임): 오른쪽으로 총총 뛰어가는 모션
• running-left (좌측 달리기, 8프레임): 왼쪽으로 달려가는 모션
• waving (인사하기, 4프레임): 손을 번쩍 들고 인사하는 모션
• jumping (점프/완료, 5프레임): 작업 성공 시 콩콩 뛰며 기뻐하는 모션
• failed (작업 실패, 8프레임): 테스트 실패나 빌드 에러 시 눈물을 글썽이는 모션
• waiting (승인 대기, 6프레임): 개발자의 확인(Yes/No) 입력을 기다리는 모션
• running (작업 수행, 6프레임): 코덱스 에이전트가 코드를 치며 집중하는 모션
• review (코드 검토, 6프레임): 생성된 코드를 세밀하게 체크하는 모션
• look (16방향 시선): 마우스 커서의 각도를 22.5도 단위로 쫓는 눈동자

터미널 한 줄로 끝내는 자동 설치 방법

터미널 명령 한 줄이면 11명의 캐릭터 에셋과 설정 파일이 자동으로 배치됩니다.

자신의 운영체제에 맞는 터미널 창을 열고 스크립트를 입력하십시오. 깃(Git) 도구가 없어도 웹 주소를 통해 최신 릴리즈 파일을 즉시 내려받습니다.

윈도우 파워셸 (Windows PowerShell)

파워셸 창을 실행한 뒤 다음 명령어를 복사하여 붙여넣습니다.

irm https://raw.githubusercontent.com/heelee912/chiikawa-dots-pets/main/install.ps1 | iex

스크립트가 실행되면 사용자 폴더 아래의 코덱스 펫 디렉터리에 폴더들이 생성됩니다. 설치 경로는 %USERPROFILE%\.codex\pets\ 입니다.

이렇게 보이면 성공: 터미널에 Installed chiikawa -> ... 부터 dekatsuyo 까지 11줄이 출력된 뒤, Done. Restart Codex and pick the pet from its pet list. 라는 완료 문구가 나오면 정상입니다.

맥OS 및 리눅스 (macOS · Linux)

터미널을 열고 다음 셸 명령어를 실행합니다.

curl -fsSL https://raw.githubusercontent.com/heelee912/chiikawa-dots-pets/main/install.sh | sh

설치 대상 경로는 기본적으로 ~/.codex/pets/ 디렉터리입니다. 외부 권한이나 추가 프로그램 설치 없이 순수 셸 스크립트로 동작합니다.

원하는 캐릭터만 골라 설치하는 팁

11명을 전부 받지 않고 좋아하는 캐릭터만 골라서 가볍게 설치할 수도 있습니다.

스크립트 실행 직전에 환경 변수 CHIIKAWA_PETS 를 지정하면 됩니다. 쉼표나 공백으로 원하는 캐릭터의 영문 식별자(ID)를 적어 줍니다.

윈도우 파워셸 선별 설치 예시

치이카와와 우사기, 하치와레 3인방만 쏙 골라 담고 싶다면 다음 명령어를 사용합니다.

$env:CHIIKAWA_PETS = "chiikawa,usagi,hachiware"
irm https://raw.githubusercontent.com/heelee912/chiikawa-dots-pets/main/install.ps1 | iex

맥OS 및 리눅스 선별 설치 예시

모몽가와 쿠리만주 선배만 골라서 데려오고 싶다면 다음과 같이 입력합니다.

CHIIKAWA_PETS="momonga kurimanju" sh -c "$(curl -fsSL https://raw.githubusercontent.com/heelee912/chiikawa-dots-pets/main/install.sh)"

터미널에 지정한 캐릭터 목록만 다운로드 완료 로그가 뜨며 용량을 아낄 수 있습니다.

직접 내려받아 수동으로 등록하기

인터넷 환경이나 회사 보안 방화벽으로 인해 스크립트 실행이 막혔다면 수동 설치가 대안입니다.

단계별로 폴더를 만들고 파일을 복사하면 1분 안에 완료됩니다.

1단계: 깃허브 저장소(github.com/heelee912/chiikawa-dots-pets)의 릴리즈(Releases) 페이지에 접속합니다. 최신 버전의 압축 파일(chiikawa-dots-pets.zip)을 내려받습니다.

2단계: 내려받은 압축 파일을 풉니다. pets 폴더 안에 캐릭터 이름별로 서브 폴더가 들어 있습니다.

3단계: 자신의 컴퓨터에 코덱스 펫 폴더를 생성합니다. 윈도우 탐색기 주소창에 %USERPROFILE%\.codex\pets 를 입력하여 이동합니다. 폴더가 없다면 .codex 폴더를 만들고 그 안에 pets 폴더를 새로 만듭니다.

4단계: 캐릭터 폴더를 복사합니다. 예를 들어 chiikawa 폴더째로 복사하여 넣습니다. 폴더 안에는 반드시 pet.json 과 spritesheet.png 두 파일이 함께 있어야 합니다.

이렇게 보이면 성공: %USERPROFILE%\.codex\pets\chiikawa\pet.json 파일이 정상 위치에 열리면 수동 설정이 끝난 것입니다.

Codex 데스크톱 앱에서 펫 불러오기

에셋 복사가 끝났다면 코덱스 데스크톱 프로그램을 완전히 종료한 뒤 다시 켭니다.

1. 열려 있는 코덱스(Codex Desktop) 창을 닫고 백그라운드 프로세스까지 재시작합니다.
2. 코덱스 설정(Settings) 메뉴로 이동한 뒤 데스크톱 펫(Desktop Pets) 탭을 선택합니다.
3. 펫 선택 드롭다운 목록을 클릭합니다.
4. 새로 추가된 Chiikawa, Hachiware, Usagi 등의 이름을 확인하고 선택합니다.
5. 저장 버튼을 누르면 작업 창 우측 하단에 귀여운 도트 캐릭터가 즉시 나타납니다.

직접 적용해 본 경험과 반응형 동작 테스트

실제 코딩 환경에 치이카와를 펫으로 등록하고 며칠간 대규모 리팩터링 작업을 진행해 보았습니다.

처음에는 단순한 도트 스티커 정도로 생각했으나 실제 체감 만족도는 상당했습니다. 긴 컴파일이나 테스트 실행 중 창을 보지 않고 있어도 펫의 행동으로 진행 상황을 알 수 있었습니다.

[개발자 코드 작성]      → 펫이 가만히 숨 쉬며 대기 (idle)
[에이전트 빌드 실행]    → 펫이 집중하여 작업 모드 돌입 (running)
[사용자 승인 요청 대기]  → 손을 모으고 고개를 끄덕임 (waiting)
[테스트 에러 발생 시]   → 눈물을 글썽이며 실패 표현 (failed)
[빌드 및 배포 완료 시]   → 양손을 들고 높이 점프 (jumping)

마우스 커서를 움직이면 눈동자가 부드럽게 커서를 쫓아옵니다. 스프라이트 시트 내 16방향 시선 처리가 자연스러웠습니다.

커서 테마와 함께 쓰면 데스크톱 몰입감이 배가됩니다. 자세한 설정은 윈도우 11 커스텀 마우스 커서 테마 적용 방법을 참고하십시오. 에이전트 성능 튜닝은 Codex 모델 활용 최적화 가이드를 확인해 보세요.

자주 겪는 문제와 해결 방법

설치 및 사용 중에 발생하기 쉬운 문제들을 정리했습니다.

펫 목록에 캐릭터 이름이 나오지 않는 경우

폴더 계층 구조가 잘못되었을 확률이 가장 높습니다. ~/.codex/pets/chiikawa/pet.json 형태여야 하며 중간에 중복 폴더가 끼어들면 안 됩니다. ~/.codex/pets/pets/chiikawa 처럼 폴더가 한 겹 더 생기지 않았는지 확인하십시오.

화면에 펫 이미지가 보라색 네모나 엑스박스로 깨져 나오는 경우

스프라이트 시트 이미지 파일 이름이 틀렸을 때 발생합니다. 이미지 파일명이 반드시 spritesheet.png 여야 합니다. 파일 확장자가 대문자 .PNG 로 되어 있지는 않은지 확인하십시오.

파워셸 스크립트 실행 시 보안 오류(Execution Policy)가 뜨는 경우

파워셸의 스크립트 실행 제한 정책 때문입니다. 파워셸 콘솔에서 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 를 한 번 실행해 준 뒤 다시 명령어를 시도하십시오.

용어 정리