MemoryLake
모든 글로 돌아가기
Tutorial2026년 11월 13일·12 분 소요

Codex Worktree란 무엇인가? 새로운 Worktree의 시작 구성 요소, 아카이브 시 삭제되는 이유, Codex가 저장하는 스냅샷 복구 방법 (2026)

Codex 채팅을 시작하고, 작성기(composer) 아래에서 Local 대신 Worktree를 선택한 뒤, 본인의 체크아웃에서 작업을 계속하는 동안 백그라운드에서 실행되도록 둡니다. 작업은 잘 진행됩니다. 몇 주 후 오래된 채팅을 열어보니 해당 채팅이 작업했던 파일들이 더 이상 디스크에 없습니다. Codex는 무언가를 복구하겠다고 제안합니다. 무슨 일이 일어난 걸까요?

OpenAI 문서의 두 가지 내용이 이를 설명해 줍니다. Worktree는 일시적으로 설계되었습니다: "기본적으로 채팅은 Codex가 관리하는 Worktree를 사용합니다. 이는 가볍고 일회용인 느낌을 주도록 의도되었습니다." 그리고 여러분이 미처 알아차리지 못한 일정에 따라 정리됩니다: "기본적으로 Codex는 가장 최근의 15개 Codex 관리 Worktree를 유지합니다."

작업 내용이 반드시 사라진 것은 아닙니다. "Codex 관리 Worktree를 삭제하기 전에, Codex는 해당 작업의 스냅샷을 저장합니다."

이 가이드는 Codex Worktree의 정의, 채팅 시작 방법, 새 Worktree에 포함되거나 제외되는 항목, Handoff를 통해 Local과 Worktree 간에 채팅을 이동하는 방법, Codex가 Worktree를 삭제하는 시점, 복구 방법, Worktree의 저장 위치, 그리고 Worktree가 보관하지 않는 항목에 대해 다룹니다.

Codex Worktree란 무엇인가

OpenAI 문서는 그 목적을 이렇게 시작합니다: "Worktree를 사용하면 Codex가 동일한 프로젝트 내에서 서로 간섭하지 않고 여러 개의 독립적인 채팅을 실행할 수 있습니다."

내부적으로 Codex Worktree는 Git worktree입니다. "Worktree는 내부적으로 Git worktree를 사용하므로 Git 저장소의 일부인 프로젝트에서만 작동합니다." 문서는 이것이 무엇을 의미하는지 설명합니다: "각 Worktree는 저장소에 있는 모든 파일의 자체 복사본을 가지지만, 커밋, 브랜치 등에 대한 동일한 메타데이터(.git 폴더)를 공유합니다."

ChatGPT 데스크톱 앱은 세 가지 용어를 사용합니다:

  • Local은 여러분 자신의 체크아웃, 즉 여러분이 생성한 저장소입니다.
  • Worktree는 앱이 로컬 체크아웃에서 생성한 Git worktree입니다.
  • Handoff는 Local과 Worktree 사이에서 채팅을 이동시키는 흐름입니다.

OpenAI는 이를 포그라운드와 백그라운드로 생각할 것을 제안합니다: "Local을 포그라운드로, Worktree를 백그라운드로 생각할 수 있습니다."

저장소와 Worktree는 프로젝트가 있는 머신에 유지됩니다. "Worktree는 휴대폰에서 로컬로 실행되지 않습니다." ChatGPT 모바일 앱은 Worktree 채팅을 시작, 안내, 승인 및 검토할 수 있지만, 이는 연결된 컴퓨터의 Codex를 제어함으로써 수행됩니다.

Worktree에서 채팅을 시작하는 방법

단계는 간단합니다:

  1. 새 채팅 보기에서 작성기 아래의 Worktree를 선택합니다. 선택적으로 설정 스크립트를 실행할 로컬 환경을 선택합니다.
  2. 작성기 아래에서 Worktree의 기반이 될 Git 브랜치를 선택합니다.
  3. 프롬프트를 제출합니다. Codex가 해당 브랜치로부터 Worktree를 생성합니다.
  4. 준비가 되면 Worktree에서 작업을 계속하거나 채팅을 Local로 전달(handoff)합니다.

프로젝트는 반드시 Git 저장소 내에 있어야 합니다.

새 Worktree의 시작 구성 요소

Worktree는 빈 폴더가 아닙니다. OpenAI 문서는 Codex가 그 안에 무엇을 넣는지 정확히 설명합니다.

브랜치의 최신 커밋. "시작 커밋은 채팅을 시작할 때 선택한 브랜치의 HEAD 커밋입니다."

커밋되지 않은 변경 사항(해당 브랜치를 선택한 경우). "로컬 변경 사항이 있는 브랜치를 선택하면, Codex는 커밋되지 않은 변경 사항도 Worktree에 적용합니다."

모든 추적된(tracked) 파일. "로컬 Codex 관리 Worktree는 Git 체크아웃에서 시작되므로 추적된 파일은 이미 존재합니다."

자체 브랜치 없음. "Worktree는 브랜치로 체크아웃되지 않습니다." 이는 detached HEAD 상태이며, 문서는 그 이유를 다음과 같이 밝힙니다: "이를 통해 Codex는 브랜치를 더럽히지 않고 여러 Worktree를 생성할 수 있습니다."

로컬 지침 재정의(override). Codex는 무시된 파일 하나를 자동으로 복사합니다. "Codex는 무시된 AGENTS.override.md를 로컬 관리 Worktree로 자동으로 복사하므로 .worktreeinclude에 나열할 필요가 없습니다." 해당 파일에 Codex를 위한 개인 지침을 보관하고 있다면, Worktree에도 해당 지침이 존재하게 됩니다.

설정 스크립트가 설치하는 모든 항목. 로컬 환경을 선택했다면 해당 설정 스크립트가 실행됩니다. OpenAI는 이것이 왜 중요한지 설명합니다: "Worktree는 로컬 채팅과 다른 디렉토리에서 실행되므로, 프로젝트가 완전히 설정되지 않았거나 저장소에 체크인되지 않은 의존성 또는 파일이 누락되었을 수 있습니다." 또한: "설정 스크립트는 Codex가 새 채팅 시작 시 새 Worktree를 생성할 때 자동으로 실행됩니다."

새 Worktree에서 제외되는 항목

Git 체크아웃에서 시작한다는 것의 이면은, 별도로 지정하지 않는 한 Git이 무시하는 모든 항목은 제외된다는 것입니다.

기본적으로 무시되는 파일들. OpenAI의 예시에는 .env 파일과 비밀(secrets) 파일이 포함됩니다. 특정 파일을 가져오려면 저장소 루트에 .worktreeinclude 파일을 추가하고 복사할 경로 또는 패턴을 나열하세요. 문서는 제한 사항에 대해 명확히 설명합니다: "Codex는 .worktreeinclude와 일치하는 무시된 파일만 복사하며, Git이 추적하지 않는 다른 로컬 파일은 복사하지 않습니다."

포함 목록에 있는 추적된 파일. "추적된 파일을 나열하지 마세요." 그것들은 이미 그곳에 있습니다.

심볼릭 링크 및 기존 파일. "Codex는 소스 심볼릭 링크를 건너뛰며, 새 체크아웃에 이미 존재하는 파일을 덮어쓰지 않습니다."

다른 종류의 Worktree. 포함 동작에는 범위가 있습니다: "이 동작은 로컬 ChatGPT 데스크톱 앱 관리 Worktree에 적용되며, 원격 Worktree나 명령줄에서 직접 생성한 Git worktree에는 적용되지 않습니다."

설치된 의존성. 설정 스크립트가 설치하지 않는 한, 새로운 Worktree에는 node_modules나 빌드 결과물이 없을 수 있습니다. 이것이 바로 로컬 환경 설정 스크립트가 필요한 이유입니다.

Local과 Worktree 간의 채팅 이동

Handoff는 채팅과 코드를 양방향으로 이동시킵니다. OpenAI 문서는 다음과 같이 설명합니다: "Local로 또는 Local로부터 전달(Handing off)하면 채팅 및 코드가 이동하므로 다른 체크아웃에서 작업을 계속할 수 있습니다."

두 가지 세부 사항이 Handoff를 예측 가능하게 만듭니다:

  • 채팅은 해당 Worktree를 유지합니다. "각 채팅은 시간이 지나도 동일한 관련 Worktree를 유지합니다. 나중에 채팅을 다시 Worktree로 전달하면, Codex는 중단했던 지점부터 다시 시작할 수 있도록 동일한 백그라운드 환경으로 되돌려 보냅니다."
  • 무시된 파일은 이동하지 않습니다. "Handoff는 Git 작업을 사용하므로, Codex가 .worktreeinclude를 통해 로컬 관리 Worktree로 복사하지 않는 한 .gitignore 파일의 일부인 파일은 채팅과 함께 이동하지 않습니다."

저희는 Codex Handoff에서 채팅과 함께 이동하는 항목 가이드에서 컴퓨터와 원격 호스트 간에 무엇이 이동하는지를 포함하여 Handoff를 자세히 다루었습니다.

사람들이 실수하기 쉬운 브랜치 규칙

Git에는 Codex가 우회할 수 없는 규칙이 있습니다. 문서는 이를 굵게 표시합니다: "Git은 브랜치가 한 번에 한 곳에서만 체크아웃되는 것을 허용합니다."

이는 Worktree를 브랜치로 전환할 때 나타납니다. Worktree에서 'Create branch here'를 선택한 다음 로컬 체크아웃에서 해당 브랜치를 체크아웃하려고 하면, Git은 해당 브랜치가 이미 Worktree에서 사용 중이라는 오류와 함께 거부합니다.

OpenAI의 조언: "브랜치를 로컬에서 체크아웃할 계획이라면, 동일한 브랜치를 두 곳에서 동시에 체크아웃 상태로 유지하려 하지 말고 Handoff를 사용하여 채팅을 Local로 이동시키세요."

Codex가 Worktree를 삭제하는 시점

Worktree는 공간을 차지합니다. "Worktree는 많은 디스크 공간을 차지할 수 있습니다. 각 Worktree는 자체 저장소 파일, 의존성, 빌드 캐시 등을 가집니다." 따라서 데스크톱 앱은 유지하는 개수를 제한합니다.

기본 제한. "기본적으로 Codex는 가장 최근의 15개 Codex 관리 Worktree를 유지합니다. 디스크 사용량을 직접 관리하고 싶다면 설정에서 이 제한을 변경하거나 자동 삭제를 끌 수 있습니다."

삭제가 발생하는 시점. 문서는 두 가지 트리거를 나열합니다:

  • 관련 채팅을 아카이브할 때.
  • 설정된 제한을 유지하기 위해 Codex가 오래된 Worktree를 삭제해야 할 때.

첫 번째 항목은 간과하기 쉽습니다. 채팅을 아카이브하는 것은 사이드바를 정리하는 것처럼 들리지만, Codex 관리 Worktree가 있는 채팅의 경우 Worktree도 삭제됩니다. Codex에서 아카이브는 다른 효과도 있으며, 이는 Codex 에이전트 커맨드 센터와 아카이브 및 삭제의 기능 가이드에서 다루었습니다.

보호되는 항목. 고정(pinned)된 채팅이 연결되어 있거나 채팅이 아직 진행 중인 경우 Codex 관리 Worktree는 자동으로 삭제되지 않습니다.

이전의 영구(permanent) Worktree. "이전 버전에서 생성된 영구 Worktree는 계속 사용 가능하며 자동 정리로부터 보호됩니다. 더 이상 프로젝트 메뉴에서 영구 Worktree를 생성할 수는 없습니다."

삭제된 Worktree를 복구하는 방법

Worktree를 삭제해도 채팅이 삭제되지는 않습니다. OpenAI의 FAQ에 따르면: "기본 Worktree 디렉토리가 삭제되더라도 채팅은 히스토리에 남아 있을 수 있습니다."

그리고 작업 내용은 먼저 저장됩니다: "Codex 관리 Worktree를 삭제하기 전에, Codex는 해당 작업의 스냅샷을 저장합니다. Worktree가 삭제된 후 채팅을 열면 복구 옵션이 표시됩니다."

따라서 복구 경로는 간단합니다. 채팅을 열고 복구 옵션을 선택하면 됩니다.

문서에는 스냅샷이 얼마나 오래 보관되는지, 또는 스냅샷에 .worktreeinclude를 통해 복사된 무시된 파일이 포함되는지는 명시되어 있지 않습니다. 로컬 비밀번호나 생성된 파일과 같이 다시 만들 수 없는 항목이 Worktree에 있었다면, 스냅샷에만 의존하지 말고 직접 복사본을 보관하세요.

Worktree의 저장 위치

"Codex는 $CODEX_HOME/worktrees에 Worktree를 생성합니다." 위치를 변경할 수 있습니다. OpenAI FAQ에 따르면 Settings를 열고 Worktrees를 선택한 다음 Worktree root를 변경하면 됩니다.

이는 홈 드라이브 용량이 작거나 더 빠른 디스크에 Worktree를 두고 싶을 때 유용합니다. 또한 디스크 공간을 수동으로 정리할 때도 알아둘 가치가 있습니다. 고정된 채팅 및 진행 중인 채팅에 대한 보호와 스냅샷 단계는 Codex 자체의 정리에 대해 문서화된 것이지, 사용자가 직접 제거하는 폴더에 대한 것이 아닙니다.

예약된 작업을 위한 Worktree

Worktree는 직접 시작한 채팅만을 위한 것이 아닙니다. "Git 저장소의 경우, 예약된 작업(scheduled tasks)은 전용 백그라운드 Worktree에서 실행되어 진행 중인 작업과 충돌하지 않도록 할 수 있습니다."

Git 외부의 프로젝트는 다르게 작동합니다: "버전 관리가 되지 않는 프로젝트에서는 예약된 작업이 프로젝트 디렉토리에서 직접 실행됩니다."

Worktree가 보관하지 않는 항목

Worktree는 파일을 보관합니다. 연결된 채팅은 대화 내용을 보관합니다. 하지만 둘 다 한 채팅에서 다음 채팅으로 이어지는 추론(reasoning), 즉 왜 이 접근 방식을 선택했는지, 어떤 대안이 실패했는지, 코드가 무엇을 기다리고 있는지 등을 보관하도록 설계되지 않았습니다.

Worktree는 설계상 일회용입니다. 하나가 삭제되면 스냅샷이 작업 내용을 유지합니다. 하지만 그 과정에서 내려진 결정들은 해당 채팅의 대화 속에 머물게 되며, 채팅이 수십 개가 되면 이를 추적하기 어려워집니다.

사람들이 먼저 시도하는 것들

정리를 위해 오래된 채팅 아카이브하기. Codex 관리 Worktree가 있는 채팅의 경우, 아카이브하면 Worktree가 삭제됩니다.

새 Worktree에 .env 파일이 있기를 기대하기. .worktreeinclude와 일치하지 않는 한 무시된 파일은 복사되지 않습니다.

Worktree의 브랜치를 로컬에서 체크아웃하기. Git은 브랜치를 한 번에 한 곳에서만 허용합니다. 대신 Handoff를 사용하세요.

Worktree 폴더를 수동으로 삭제하기. 스냅샷 단계는 Codex 자체 정리 시에만 적용되며, 직접 삭제하는 폴더에는 적용되지 않습니다.

Worktree와 함께 채팅도 사라졌다고 가정하기. 채팅은 히스토리에 남아 있을 수 있으며, 채팅에서 Worktree를 복구할 수 있습니다.

해결책: 작업 손실 없이 Worktree 사용하기

1단계: 새 Worktree에 필요한 사항 설정

의존성을 위한 로컬 환경 설정 스크립트와 Worktree에 필요한 무시된 파일들을 위한 .worktreeinclude 파일을 추가하세요.

2단계: 다시 돌아올 채팅 보호하기

Worktree를 유지하고 싶은 채팅은 고정(Pin)하거나, 설정에서 제한 개수를 늘리세요.

3단계: 다시 작업하는 대신 복구하기

Worktree가 삭제되었다면, 처음부터 다시 시작하기 전에 채팅을 열어 복구 옵션을 사용하세요.

4단계: 추론 내용 기록하기

접근 방식이나 제외한 대안 등 Worktree 변경 사항 뒤에 숨겨진 결정 사항들을 채팅 외부의 별도 장소에 보관하세요.

MemoryLake에서 설정하기

Worktree는 병렬 작업을 위한 좋은 장소이며, Codex는 정리 전에 이를 신중하게 저장합니다. 하지만 그 작업 뒤에 숨겨진 결정 사항들은 새 Worktree나 Local에서의 다음 채팅이 다시 묻지 않고도 이어받아야 할 내용입니다.

MemoryLake는 결정, 제약 조건, 컨벤션과 같은 프로젝트 컨텍스트를 한 곳에서 유지하고 ChatGPT, Claude Code, Codex와 같이 연결된 어시스턴트가 사용할 수 있게 해주는 메모리 레이어입니다.

여러분은 자신의 언어로 직접 항목을 작성합니다. 여러분의 Worktree, 스냅샷, Codex 채팅, .worktreeinclude 또는 AGENTS.override.md 파일, Codex 메모리 또는 기타 벤더의 저장소에서 어떠한 내용도 읽거나 쓰거나 삭제하지 않습니다. Worktree, Handoff 및 정리는 OpenAI가 설명한 방식 그대로 작동합니다.

1단계: API 키 생성

로그인 후 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 저장소 외부에 보관하고 .worktreeinclude에 추가하지 마세요.

에이전트에서 사용하기 위해 새 키를 생성하고 복사하는 API 키 화면을 보여주는 MemoryLake 콘솔
에이전트에서 사용하기 위해 새 키를 생성하고 복사하는 API 키 화면을 보여주는 MemoryLake 콘솔

2단계: 첫 번째 메모리 업로드

해결책의 4단계에서 작성한 내용으로 시작하세요. 각 작업에 대한 접근 방식, 시도했던 대안, 그리고 이를 형성한 제약 조건들입니다. 한 항목당 하나의 결정을 담으세요.

첫 번째 문서가 업로드된 MemoryLake 워크스페이스, 각 파일이 검색 가능한 메모리가 됨에 따라 목록에 표시됨
첫 번째 문서가 업로드된 MemoryLake 워크스페이스, 각 파일이 검색 가능한 메모리가 됨에 따라 목록에 표시됨

3단계: AI 및 에이전트 연결

Codex 및 사용하는 다른 어시스턴트를 연결하세요. 새로운 Worktree에서의 새 채팅이나 Local로 전달된 채팅 모두 동일한 결정 사항을 활용할 수 있습니다.

메모리 레이어에 연결할 수 있는 AI 클라이언트 및 에이전트 프레임워크를 나열한 MemoryLake 통합 화면
메모리 레이어에 연결할 수 있는 AI 클라이언트 및 에이전트 프레임워크를 나열한 MemoryLake 통합 화면

실제적인 변화

첫 번째 차이점은 정리가 더 이상 여러분의 추론에 위협이 되지 않는다는 것입니다. Worktree가 아카이브되고 삭제되더라도 그 뒤의 결정 사항들은 여전히 기록되어 있습니다.

두 번째는 병렬 채팅의 시작이 빨라진다는 것입니다. 각 새로운 Worktree 채팅은 프로젝트의 확정된 결정 사항을 다시 발견하는 대신 바로 활용할 수 있습니다.

세 번째는 도구 간의 연속성입니다. 동일한 저장소에서 작업하는 Claude Code나 다른 어시스턴트도 동일한 항목을 사용할 수 있습니다.

Codex Worktree를 위한 모범 사례

백그라운드 작업에 Worktree를 사용하세요. 활발히 테스트 중인 작업은 Local에 유지하세요.

설정 스크립트를 추가하세요. 무언가가 설치하지 않는 한 새 Worktree에는 의존성이 없을 수 있습니다.

무시된 파일을 .worktreeinclude에 나열하세요. 일치하는 무시된 파일만 복사됩니다.

다시 방문할 항목은 고정하세요. 고정된 채팅은 Worktree를 유지합니다.

신중하게 아카이브하세요. 아카이브하면 채팅의 Codex 관리 Worktree가 삭제됩니다.

다시 하기 전에 복구하세요. Codex는 관리 Worktree를 삭제하기 전에 스냅샷을 저장합니다.

이유(Why)는 다른 곳에 보관하세요. Worktree는 파일을 보관할 뿐, 이유는 보관하지 않습니다.

결론

Codex Worktree는 ChatGPT 데스크톱 앱이 로컬 체크아웃을 건드리지 않고 백그라운드에서 채팅이 작업할 수 있도록 생성하는 Git worktree입니다. 선택한 브랜치의 HEAD 커밋에서 시작하며, 해당 브랜치에 있던 커밋되지 않은 변경 사항을 포함하고, 모든 추적된 파일을 가지며, .worktreeinclude에 나열한 무시된 파일과 AGENTS.override.md만 복사합니다.

Codex는 기본적으로 가장 최근의 15개 관리 Worktree를 유지하며, 채팅을 아카이브할 때 해당 Worktree를 삭제합니다. 고정된 채팅과 진행 중인 채팅은 보호되며, 관리 Worktree를 삭제하기 전에 Codex는 채팅에서 복구할 수 있는 스냅샷을 저장합니다. 작업 뒤에 숨겨진 추론은 다음 채팅이 읽을 수 있는 곳에 보관하세요.

자주 묻는 질문

Codex에서 Worktree란 무엇인가요?

Codex 채팅이 다른 채팅과 간섭하지 않고 병렬로 작업할 수 있도록 ChatGPT 데스크톱 앱이 로컬 체크아웃에서 생성하는 Git worktree입니다.

왜 내 Codex Worktree가 사라졌나요?

Codex는 채팅을 아카이브하거나 기본 15개인 제한 개수를 유지해야 할 때 관리 Worktree를 삭제합니다.

삭제된 Codex Worktree를 복구할 수 있나요?

네. Codex는 관리 Worktree를 삭제하기 전에 스냅샷을 저장하며, 채팅을 열면 복구 옵션이 표시됩니다.

왜 내 .env 파일이 Worktree에 없나요?

무시된 파일은 저장소 루트의 .worktreeinclude 패턴과 일치하지 않는 한 복사되지 않습니다.

Codex는 Worktree를 어디에 저장하나요?

기본적으로 $CODEX_HOME/worktrees에 저장합니다. Settings > Worktrees > Worktree root에서 위치를 변경할 수 있습니다.

왜 Worktree의 브랜치를 로컬에서 체크아웃할 수 없나요?

Git은 브랜치가 한 번에 한 곳에서만 체크아웃되는 것을 허용합니다. 대신 Handoff를 사용하여 채팅을 Local로 이동시키세요.

Codex 채팅을 아카이브하면 Worktree가 삭제되나요?

네. 관련 채팅을 아카이브하는 것은 Codex 관리 Worktree를 삭제하는 트리거 중 하나입니다.