Fei-Away/Codex-Dream-Skin 딥다이브
— 공식 Codex 데스크톱 앱에 "숨 쉬는 얼굴"을 입히다

1프로젝트 한 줄 요약

Codex Dream Skin은 "공식 Codex 데스크톱 앱의 얼굴만 갈아입히는 겉옷"이다. 프로젝트의 한 줄 표어가 정확히 이걸 말한다 — "给 Codex 桌面端换一张会呼吸的脸"(Codex 데스크톱에 숨 쉬는 얼굴 한 장을 입히자). 사용자가 자기가 고른 이미지 한 장을 넣으면, 그 이미지가 Codex 창 전체를 덮는 끊김 없는 16:9 배경이 되고, 그 위로 Codex의 원래 사이드바·입력창·프로젝트 카드가 여전히 진짜로 작동하는 채 얹힌다.

핵심 동작을 한 문장으로 요약하면 이렇다. 공식 Codex 앱을 "원격 디버깅 포트"를 열고 실행 → 그 포트에 웹소켓으로 붙어 → 미리 만든 CSS(배경·색)와 JS(DOM 정리)를 앱 안으로 밀어 넣는다. 이 통로가 바로 CDP(Chrome DevTools Protocol)다. 브라우저 개발자도구가 페이지를 조종할 때 쓰는 바로 그 프로토콜을, 이 도구는 "테마를 입히는 손"으로 재활용한다(자세한 흐름은 §4).

중요한 건 "하지 않는 것"의 목록이다. 이 도구는 Codex의 설치 파일(.app/app.asar/WindowsApps)을 고치지 않고, 코드 서명도 건드리지 않으며, 당신의 API 키·모델 주소도 만지지 않고, 당신의 이미지를 어디에도 업로드하지 않는다. 모든 변경은 당신 컴퓨터 안(loopback)에서 런타임에만 일어나고, 클릭 한 번(Restore)으로 원상 복구된다. "공식 앱을 안 부수면서 겉만 바꾼다"가 설계 철학이다.

2왜 지금 주목받는가

이 저장소가 하루 만에 TrendShift Daily #2(모멘텀 5.2k)로 치고 올라온 데는 기술만큼이나 "이야기"가 있다. 발단은 이렇다 — 중국 중고거래 앱 闲鱼(셴위)에서 누군가 "Codex 앱 테마 스킨"을 한 개 66위안, 99위안에 팔고 있었다. 이를 본 개발자들이 "이건 chatgpt-image(gpt-image)로 이미지 몇 장 뽑고 CSS 몇 줄 얹으면 되는 걸 파는, 妥妥的智商税(전형적인 호갱 상술)"라며 동작하는 오픈소스 스킬을 그냥 무료로 공개해 버렸다. Codex Dream Skin이 바로 그 결과물이다.

여기에 "예쁜 화면"이 불을 붙였다. 소셜에는 玫瑰金(로즈골드) 배색, 인물 立绘(일러스트) 배치, 사이드바·입력창·버튼까지 통일된 핑크 계열, "우리 무엇을 만들까?" 환영 화면까지 다시 칠한 스크린샷이 돌았다. "그냥 벽지 한 장 붙인 게 아니라 완결된 비주얼 경험"이라는 반응이 커뮤니티를 자극했다.

주목 포인트 1 — "앱을 안 부수는" 스킨이라는 접근

서드파티 앱을 꾸미는 흔한 방법은 app.asar(Electron 앱의 압축된 소스)를 뜯어 파일을 갈아치우는 것이다. 하지만 그러면 코드 서명이 깨지고, 앱 업데이트 때마다 다시 뜯어야 하고, 잘못하면 앱이 안 뜬다. Codex Dream Skin은 이 위험을 통째로 피한다. 설치 파일에 손대는 대신, 앱을 원격 디버깅 모드로 켜서 CDP로 스타일만 얹는다. 최악의 경우라도 "그냥 배경이 안 맞는" 화면일 뿐, 앱이 망가지지 않는다. 복구는 클릭 한 번. 서드파티 데스크톱 앱을 안전하게 커스터마이즈하는 정석적 패턴이다.

주목 포인트 2 — 벽지 한 장으로 "읽히는" UI를 만드는 기술

배경 이미지를 UI 뒤에 깔면 보통 글자가 안 보인다. 이 프로젝트의 진짜 기술은 이미지를 그냥 깔지 않고, 반투명 그라데이션 장막(scrim)을 알파값을 조절해 겹쳐 Codex의 원래 글자·버튼이 계속 읽히게 만드는 CSS다(1,079줄). 게다가 주입된 JS가 브라우저 Canvas로 이미지의 대표색·밝기·초점을 분석해 그 이미지에 어울리는 UI 색을 자동으로 뽑아낸다 — 이 모든 걸 서버 없이, 업로드 없이 당신 컴퓨터 안에서.

주목 포인트 3 — "스킬"로 포장돼 에이전트가 직접 깐다

이 저장소는 단순 스크립트 모음이 아니라 Agent Skill 형식(SKILL.md + YAML 머리말)으로도 포장돼 있다. 그래서 폴더를 통째로 자기 Codex 에이전트에게 건네고 "내 사진으로 테마 설치하고 검증까지 해줘"라고 말하면, 에이전트가 설치→커스터마이즈→검증→(원하면)복구 절차를 스스로 수행한다. "사람이 쓰는 도구"이자 "에이전트가 실행하는 스킬"인 이중 포장이다.

3기술 스택 전체 지도

GitHub 언어 통계는 이 저장소를 Shell(18개 .sh + 9개 .ps1)로 분류하지만, 그건 겉포장일 뿐이다. 실제 로직은 Node로 짠 CDP 주입기(injector.mjs), 1,079줄짜리 테마 CSS, 786줄짜리 렌더러 주입 JS에 들어 있다. 스택은 "① 어떻게 앱에 붙는가(주입) → ② 무엇을 그리는가(테마) → ③ 어떻게 관리하는가(트레이/설정)"의 세 축으로 보면 깔끔하다.

① 앱에 붙는 층 (주입 · 실행)

② 화면을 그리는 층 (테마 · 렌더러)

③ 관리하는 층 (트레이 · 설정 · 프리셋)

4아키텍처 심화 분석 — CDP 주입의 실체

4-1. 전체 흐름도 — 이미지 한 장이 앱 배경이 되기까지

가장 빠른 이해법은 "당신이 고른 사진"이 어떤 부품을 거쳐 "Codex 창의 배경"으로 나타나는지 따라가는 것이다. 핵심은 공식 Codex를 원격 디버깅으로 켜고, 그 창(렌더러)에 CSS+JS를 주입하는 한 줄기 파이프라인이다.

4-2. 1·2단계 — "아무 창에나 주입하지 않는다"는 안전장치

주입기가 처음 하는 일은 붙을 대상(CDP 타깃)이 정말 내 컴퓨터 안의 Codex 렌더러가 맞는지 깐깐하게 검증하는 것이다. 조금이라도 이상하면(외부 호스트, 포트 불일치, 계정정보 포함, app://가 아닌 URL 등) 즉시 거부한다. 원격 디버깅 포트는 인증이 없기 때문에, 이 형태 검사가 사실상의 방어선이다.

// injector.mjs — CDP 웹소켓 타깃을 loopback·포트·경로 형태로 검증(요지)
function validatedDebuggerUrl(target, port) {
  const url = new URL(target.webSocketDebuggerUrl);
  const pathIsValid = /^\/devtools\/page\/[A-Za-z0-9._-]{1,200}$/.test(url.pathname);
  if (url.protocol !== "ws:" || !LOOPBACK_HOSTS.has(url.hostname)
      || Number(url.port) !== port || url.username || url.password
      || url.search || url.hash || !pathIsValid)
    throw new Error("Rejected a CDP WebSocket URL outside the allowed loopback page endpoint shape");
  return url.href;
}

포인트는 "허용 목록(loopback 호스트) + 엄격한 경로 정규식 + 군더더기(쿼리·해시·인증정보) 전면 금지"를 한꺼번에 요구한다는 것이다. 이렇게 "정상 모양"을 아주 좁게 정의해 두면, 예상치 못한 형태는 전부 걸러진다. 서드파티 앱을 자동으로 조종할 때 "붙을 대상부터 의심하라"는 교과서적 방어다.

4-3. 3·4·5단계 — 페이로드 조립과 "깜빡임 없는" 주입

검증을 통과하면 주입기가 loadPayload()로 재료를 모은다 — dream-skin.css, 렌더러 JS 템플릿, 테마 이미지(base64 data: URL), theme.json. 그리고 템플릿의 자리표시자를 JSON.stringify로 안전하게 치환해 하나의 실행 문자열을 만든다.

// injector.mjs — 자리표시자를 실제 값으로 치환해 페이로드 완성(요지)
const payload = template
  .replace("__DREAM_SKIN_CSS_JSON__",   JSON.stringify(css))
  .replace("__DREAM_SKIN_ART_JSON__",   JSON.stringify(artDataUrl))   // 이미지=base64
  .replace("__DREAM_SKIN_THEME_JSON__", JSON.stringify(theme));

// 즉시 적용: 현재 세션에서 실행
await session.evaluate(payload);              // = CDP Runtime.evaluate

// 지속 적용: 새 문서가 로드되기 "전에" 미리 심어 깜빡임 방지
await session.send("Page.addScriptToEvaluateOnNewDocument", { source: payload });

여기 watch 모드의 영리함이 있다. 단순히 지금 화면에 Runtime.evaluate로 한 번 칠하면, 앱이 페이지를 새로고침(라우팅·리로드)할 때 스킨이 잠깐 벗겨졌다가 다시 칠해져 깜빡인다. 그래서 Page.addScriptToEvaluateOnNewDocument로 "새 문서가 뜰 때마다 이 스크립트를 가장 먼저 실행"하도록 예약해, Codex 자신의 로드가 끝나기 전에 배경이 이미 깔려 있게 한다. 여기에 테마 폴더를 fs.watch로 감시해, 이미지·색을 바꾸면 내용 해시(revision) 비교로 멱등하게 핫 리로드한다.

4-4. 배경이 UI를 안 가리는 비결 — scrim 그라데이션

배경 이미지를 그냥 깔면 글자가 묻힌다. dream-skin.css는 이미지를 CSS 변수로 받아, 그 위에 배경색을 알파값으로 단계 조절한 그라데이션 장막(scrim)을 겹친다. 왼쪽(글자·입력창이 있는 쪽)은 진하게 덮어 가독성을 지키고, 오른쪽(인물·풍경 쪽)은 투명하게 열어 이미지를 보여주는 식이다.

/* dream-skin.css — 작업 화면 배경: 장막 + 그늘 + 이미지를 겹쳐 쌓기 */
main.main-surface:not(.dream-skin-home-shell)::before {
  background-image: var(--ds-task-fade), var(--ds-task-shade), var(--dream-skin-art);
}
/* 왼쪽 90% 불투명 → 오른쪽 0%로 열리는 장막 = 글자쪽만 진하게 덮음 */
--ds-hero-scrim: linear-gradient(90deg,
  rgb(var(--ds-bg-rgb)/.90) 0%,  rgb(var(--ds-bg-rgb)/.76) 50%,
  rgb(var(--ds-bg-rgb)/.18) 84%, transparent 100%);

이미지의 초점 위치도 데이터로 잡는다 — theme.json의 art.focusX/Y(0~1)를 background-position %로 바꿔, 인물의 얼굴이 오른쪽 "안전지대"에 오도록 배치한다. 그래서 사실 이 프로젝트에는 별도의 "인물 그리기" 레이어가 없다 — 인물은 그냥 배경 이미지 한 장에 이미 들어 있고, CSS는 그걸 focusX≈0.72 + safeArea:"left"로 오른쪽에 놓아 Codex의 원래 글자·입력창이 왼쪽 여백에 얹히게 만들 뿐이다. 사이드바·입력창도 Codex의 원래 DOM을 반투명 색으로 다시 칠하는 정도다.

4-5. 안전 — 설정 파일을 건드릴 때의 방어 3종

스킨이 Codex 설정(config.toml)에서 손대는 건 외형 키 2개뿐이지만, 그 최소 편집조차 사고 없이 하려고 theme-config.mjs는 세 겹의 방어를 건다. 이 부분이 "겉옷 주제에 안 어울리게 진지한" 이 저장소의 백미다.

여기에 엄격한 UTF-8 처리(Buffer.from(content).equals(bytes)로 인코딩 왕복 검증)까지 더해진다. Windows 쪽은 같은 걸 config-utf8.ps1로 옮겼는데, 최신 커밋(2026-07-17, #71)이 바로 "PowerShell 5.1에서 원자적 교체 지원"을 고친 것이다 — 이 방어를 얼마나 진지하게 여기는지 보여주는 대목이다.

5디렉토리 구조 해부

저장소는 크지 않지만(추적 파일 133개) 규칙적이다. 뼈대는 같은 설계를 각자 재구현한 두 제품 — macos/(Bash+Node)와 windows/(PowerShell+Node) — 그리고 둘이 공유하는 docs/다. 아래는 "무엇을 먼저 읽어야 하는가" 관점의 지도다.

6학습 포인트

배울 것 1 — CDP로 앱을 "안 부수고" 조종하기

이 저장소의 최고 교재 가치. 원격 디버깅 포트로 Electron 앱을 켜고 → 웹소켓 타깃을 형태 검증하고 → Runtime.evaluate로 주입하고 → addScriptToEvaluateOnNewDocument로 재로드에 대비하고 → window.__…_STATE__의 cleanup으로 완전히 원복하는 흐름은, "가역적 런타임 스킨"의 정석 아키텍처다. 앱 바이너리·서명을 안 건드리므로 업데이트에도 강하다. 다른 Electron 앱(에디터·메신저)을 꾸미고 싶을 때 그대로 응용된다.

배울 것 2 — 서드파티 설정 파일을 겁 없이 고치는 법

theme-config.mjs(314줄)는 그 자체로 하나의 마스터클래스다. ① 대상 테이블([desktop])만 다시 쓰고 여러 줄 문자열·배열·중복 키·심볼릭 링크는 거부, ② 임시 파일 + fs.rename의 원자적 쓰기, ③ lstat dev/ino 신원 확인 + 교체 직전 바이트 재검증, ④ 죽은 소유자를 kill(pid,0)으로 감지하는 디렉토리 락, 여기에 엄격한 UTF-8 왕복 검증까지. "남의 설정 파일을 안전하게 만지는" 모든 요령이 한 파일에 압축돼 있다.

배울 것 3 — 의존성 0으로 이미지(PNG) 만들기

generate-presets.mjs(116줄)는 외부 라이브러리 없이 PNG를 손으로 인코딩한다 — 자체 CRC32 테이블, IHDR/IDAT/IEND 청크, zlib.deflateSync. 여기에 밴딩을 없애는 자체 value-noise 디더링과 screen 블렌드로 은은한 오로라 배경을 결정적으로(byte-identical) 생성한다. 재실행해도 커밋된 에셋과 완전히 같아 diff가 안정적이고, 실사 이미지의 초상권 문제도 우회한다. "포맷을 이해하면 라이브러리 없이도 만든다"의 좋은 예.

배울 것 4 — 이미지에서 UI 색을 뽑는 클라이언트 사이드 자동화

주입된 렌더러가 브라우저 Canvas로 배경 이미지를 24색 구간으로 다운샘플해 대표 accent·휘도·초점·안전변(좌/우)을 추출하고, 그걸로 UI 팔레트를 자동 유도한다. 서버·업로드·API 키가 전혀 없어 프라이버시를 지키면서 "이미지 → 어울리는 테마"를 실현한다. 색 이론과 Canvas API를 실전에서 어떻게 엮는지 배우는 표본.

배울 것 5 — SKILL.md 형식으로 "에이전트가 실행하는 도구" 포장하기

같은 도구를 사람이 더블클릭으로도, 에이전트가 스킬로도 쓰게 만든 이중 포장. SKILL.md의 YAML 머리말(name·description) + 절차 본문은 Anthropic/Claude 스킬 관례와 같은데, 이 저장소는 그걸 agents/openai.yaml로 Codex에 등록한다(.claude-plugin/marketplace.json은 없음 — Claude 플러그인이 아니라 Codex 스킬). "한 형식으로 여러 에이전트 생태계에 얹기"의 사례다.

배울 것 6 — 프로세스 신원(identity) 안전

저장된 PID·경로를 절대 그냥 믿지 않는다. 프로세스를 멈추거나 재사용하기 전에 PID + 실행 파일 + 명령줄 + 시작 시각(mac) 또는 패키지 신원(win)이 모두 일치해야만 진행한다. "PID는 재사용된다"는 함정을 아는 설계로, 어떤 데몬 관리자에게나 값진 패턴이다.

7시스템 · 실행 요구사항

이 도구는 자기 앱이 아니라 이미 설치된 공식 Codex 데스크톱 앱에 얹히는 것이라, 요구사항의 절반은 "Codex가 먼저 있어야 한다"이다. 이미지 생성은 이 저장소가 하지 않으므로(§아래 주의) gpt-image 크레딧 같은 것도 이 도구 자체엔 필요 없다.

8직접 해볼 수 있는 실습 과제

먼저 설치. 공식 Codex 데스크톱 앱이 이미 있다는 전제하에, macOS 기준 흐름이 가장 직관적이다.

# macOS — 저장소에서 설치 후 프리셋 적용
cd macos
./scripts/install-dream-skin-macos.sh --no-launch        # ~/.codex/…에 설치
~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh --id preset-romantic-rose
# 이후 바탕화면의 "Codex Dream Skin.command" 더블클릭 → 스킨 켠 채 Codex 실행

# Windows
powershell -ExecutionPolicy Bypass -File .\windows\scripts\install-dream-skin.ps1
powershell -ExecutionPolicy Bypass -File .\windows\scripts\start-dream-skin.ps1

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식
· GitHub 저장소: github.com/Fei-Away/Codex-Dream-Skin (MIT © 2026 · v1.2.0 · ★5.2k · GitHub 언어=Shell)
· TrendShift 카드: trendshift.io/repositories/84043 (Daily #2 · #AI skills)
· 설치: 저장소 클론 후 macos/scripts/install-dream-skin-macos.sh 또는 windows/scripts/install-dream-skin.ps1

저장소 안에서 꼭 읽을 것
· macos/scripts/injector.mjs — CDP 주입 엔진(타깃 검증·페이로드·watch)
· macos/scripts/theme-config.mjs — 서드파티 설정 안전 패치(원자적·신원검증·락)
· macos/assets/dream-skin.css · renderer-inject.js — 테마 CSS + 렌더러 주입/색분석
· macos/presets/generate-presets.mjs — 의존성 0 PNG 인코더
· macos/SKILL.md · windows/SKILL.md — 에이전트 절차서 + agents/openai.yaml 등록
· docs/background-generation-prompts.md — UI 없는 배경을 만드는 AI 프롬프트 8종

곁들여 학습
· Chrome DevTools Protocol 문서 — Runtime·Page 도메인
· Electron 앱 구조(메인/렌더러·app.asar)와 안전한 커스터마이즈
· PNG 포맷(청크·CRC32·zlib) · Canvas 색추출 · CSS 그라데이션/가독성
· Agent Skill(SKILL.md) 패키징 — Codex(agents/openai.yaml) vs Claude Code 이식성
· 이미 분석한 다른 Claude/Codex 스킬 딥다이브들과 비교(§인덱스 cat-claude-skills)