Codex CLI 워크트리 실전 가이드: 격리부터 결과 반영까지

Codex CLI 워크트리, 가장 빠르게 시작하는 법

Codex CLI 0.154.0과 로컬 Git 저장소가 필요하며, 실험 기능인 worktrees를 활성화해야 합니다. 구버전 바이너리에는 없는 플래그를 찾느라 시간을 쓰지 않도록 먼저 버전을 확인합니다.

codex --version
npm install -g @openai/codex@0.154.0
codex features enable worktrees
codex features list

위 영구 설정 명령을 실행하면 기능 선택이 Codex 설정에 기록됩니다. 한 번만 시험해 보고 싶다면 설정은 그대로 두고 해당 실행에 --enable worktrees를 추가하면 됩니다.

이제 새 격리 세션이나 헤드리스 작업을 시작하거나, 기존 대화를 분기할 수 있습니다.

codex --enable worktrees --worktree "Upgrade the test runner and run its suite"
codex exec --enable worktrees --worktree "Find the flaky test and propose the smallest fix"
codex fork --enable worktrees --worktree <session-id> "Try the lower-risk implementation"

대화형 분기에서 <session-id>는 /status에 표시되는 채팅 ID입니다. 0.154.0에서는 이 ID를 반드시 명시해야 합니다. codex fork --worktree --last는 허용되지 않습니다.

터미널 인터페이스에서도 같은 흐름을 이용할 수 있습니다. /worktree를 입력한 뒤 현재 대화를 새 체크아웃에서 이어갈지, 그곳에서 새 대화를 시작할지, 아니면 이 저장소에서 Codex가 이미 관리 중인 워크트리를 둘러볼지 선택합니다.

Codex가 실제로 만드는 것

관리형 워크트리는 같은 Git 저장소에 연결된 두 번째 체크아웃입니다. 하나의 도서 목록을 두 열람실이 함께 쓴다고 생각하면 이해하기 쉽습니다. 각 열람실에는 서로 다른 페이지를 펼쳐 둘 수 있지만, 커밋과 브랜치는 같은 목록을 참조합니다.

Codex는 소스 저장소의 커밋된 HEAD를 기준으로 detached HEAD 상태의 새 체크아웃을 만든 뒤, 이를 새 세션에 연결합니다. detached HEAD란 체크아웃이 이름 있는 브랜치를 따라가는 대신 특정 커밋을 직접 가리키는 상태입니다. 원래 체크아웃의 위치와 상태는 그대로 유지됩니다.

깨끗한 출발점에는 분명한 제약이 있습니다. 원래 체크아웃에서 아직 커밋하지 않은 수정 사항은 새 세션으로 따라오지 않습니다. 일반적인 .env나 node_modules 디렉터리처럼 무시된 파일도 마찬가지입니다. OpenAI는 Desktop이 관리하는 로컬 워크트리에 대해 .worktreeinclude 복사 방식을 안내하지만, 명령줄에서 만든 워크트리는 그 대상이 아니라고 명시합니다. 따라서 CLI 경로에서는 작업에 필요한 환경을 별도로 준비해야 합니다.

저장소 안쪽의 하위 디렉터리에서 Codex를 실행하면 관리형 체크아웃에서도 그 상대 경로가 유지됩니다. 예를 들어 apps/web에서 시작했다면, 커밋된 리비전에 해당 디렉터리가 존재하는 한 새 워크트리 안의 동일한 apps/web 디렉터리에 세션이 배치됩니다.

시작부터 결과 보존까지, 실전 워크플로

가장 안전한 흐름은 다섯 단계입니다. 깨끗한 상태에서 시작하고, 올바른 위치인지 확인한 다음, 작업을 수행하고 근거를 검토한 뒤, 결과를 보존할지 버릴지 명확히 결정합니다.

1. 실제로 원하는 커밋에서 시작합니다

--worktree는 브랜치나 기준점을 고르는 옵션이 아니라 불리언 스위치입니다. 지정한 저장소의 HEAD에서 시작합니다. 실행 전에 원하는 기준 브랜치를 체크아웃하고, 작업에 필요한 소스 변경 사항은 먼저 커밋합니다. 특정 로컬 체크아웃을 가리키려면 -C <repo-path>를 사용할 수 있습니다.

독립적인 작업이라면 새 세션을 사용합니다. 새 시도가 기존 대화의 결정 사항과 제약을 이어받아야 한다면 분기를 사용합니다. 분기하면 대화 기록은 새 채팅에 보존되고 작업은 격리된 체크아웃으로 이동하므로, 첫 번째 시도도 비교할 수 있는 상태로 남습니다.

2. 편집하기 전에 체크아웃을 확인합니다

세션을 시작하면 Codex에 pwd, git status --short, git rev-parse --short HEAD를 실행하도록 요청합니다. 작업 디렉터리는 관리형 경로여야 하고, 상태는 깨끗해야 하며, 커밋은 의도했던 소스 HEAD와 일치해야 합니다.

이 간단한 확인으로 비용이 가장 큰 단순 실수를 막을 수 있습니다. 엉뚱한 기준점에서 훌륭한 작업을 완성하는 상황입니다.

3. 이 작업에 필요한 것만 설치합니다

워크트리가 격리하는 것은 체크아웃된 파일입니다. 컨테이너를 만들거나, 포트를 예약하거나, 데이터베이스를 복제하거나, 의존성을 설치해 주지는 않습니다. 관리형 체크아웃에서 저장소의 표준 설정 명령을 실행해야 합니다. 동시에 실행하는 세션끼리 충돌할 수 있다면 각각 별도의 포트, 임시 데이터베이스, 캐시 디렉터리, 테스트 계정을 배정합니다.

반드시 이해해야 할 핵심 한계입니다. Git diff가 둘 다 깨끗하더라도 두 세션이 같은 개발 데이터베이스를 마이그레이션하거나 같은 포트를 사용하면 서로 간섭할 수 있습니다.

4. diff를 검토하고 올바른 대화를 재개합니다

워크트리 세션 안에서는 /review로 커밋하지 않은 변경 사항을 검사할 수 있습니다. 다른 터미널에서 확인하려면 먼저 /worktree를 열고 Browse worktrees를 선택한 다음, 원하는 체크아웃에서 Copy working directory를 선택합니다. 이어서 git -C "<worktree-path>" status --short, git -C "<worktree-path>" diff --stat, git -C "<worktree-path>" diff를 실행합니다.

codex review --worktree는 실행하지 마십시오. 0.154.0에서는 이 플래그 조합을 거부합니다. 활성 워크트리의 세션 내부에서 검토하거나, 복사한 경로를 일반 검토 도구에 지정해야 합니다.

나중에 이어서 작업하려면 /worktree를 입력하고 Browse worktrees에서 관리형 체크아웃을 고른 뒤 Resume owner thread를 선택합니다. --worktree를 codex resume에 붙이지 마십시오. 재개할 때는 세션에 이미 연결된 체크아웃으로 돌아가야지, 새 워크트리를 또 할당해서는 안 됩니다.

5. 체크아웃을 정리하기 전에 변경 사항을 보존합니다

남길 변경이라면 관련 테스트를 실행하고 워크트리에서 커밋한 뒤 커밋 SHA를 복사합니다. 원래 체크아웃에서는 git cherry-pick <sha>로 그 커밋을 현재 브랜치에 가져옵니다. detached 커밋이 사라지지 않도록 워크트리를 제거하기 전에 cherry-pick해야 합니다.

별도의 리뷰 브랜치가 더 적합하다면 워크트리에서 git switch -c codex/<task>를 실행하고 커밋한 다음 푸시하고 풀 리퀘스트를 엽니다. Git은 같은 브랜치를 원래 체크아웃과 워크트리에서 동시에 체크아웃하도록 허용하지 않습니다. 워크트리에서 바로 푸시하거나, 해당 워크트리를 제거한 뒤 다른 곳에서 브랜치를 체크아웃합니다.

CLI에서 만든 워크트리는 자동으로 정리되지 않습니다. 변경 사항을 안전하게 커밋했거나 의도적으로 폐기했다면 체크아웃이 깨끗한지 확인한 뒤, 소스 저장소에서 git worktree remove <worktree-path>를 실행합니다. --force는 피합니다. git worktree prune으로 나중에 오래된 Git 등록 정보를 지울 수는 있지만, 세션이 아직 체크아웃을 사용 중인지 확인하는 절차를 대신할 수는 없습니다.

Codex CLI 워크트리가 비용 구조에 미치는 영향

기본 기능이 생기면서 작지만 반복되던 셸 작업이 줄었습니다. 0.154.0 이전에는 CLI 사용자가 직접 경로를 만들고, 브랜치를 생성하거나 분리하고, 그 디렉터리에서 Codex를 실행하고, 어느 채팅이 어느 작업에 해당하는지 기억한 다음, Git과 세션 상태를 모두 정리해야 했습니다. 이제 새 플래그가 체크아웃 생성과 세션 연결을 한 번에 처리하고, /worktree는 저장소를 인식하는 탐색 및 재개 경로를 제공합니다.

기존 Codex 구독자에게 체크아웃을 위한 별도 공개 요금은 없습니다. Codex Plus는 월 $20입니다. 병렬 워크트리를 정리해 주는 상용 에이전트 워크스페이스 Unstoppable은 유료 Pro 플랜이 월 $19부터 시작하며, Business는 사용자당 $29, Enterprise는 사용자당 $49입니다. 체크아웃 생성과 세션 재개라는 좁은 용도라면 이제 기본 Codex만으로 이미 쓰고 있는 구독 안에서 해결할 수 있습니다.

하지만 유료 워크스페이스 범주 전체를 대체하는 것은 아닙니다. 에이전트 통합 대시보드, 포트 할당, 공유 환경 설정, 테스트 결과 취합, 풀 리퀘스트 추적, 팀 정책, 비용 보고는 여전히 단순 체크아웃보다 상위 계층에 있습니다. 병렬 세션 역시 같은 Codex 사용량 한도를 소모합니다. 따라서 비용 측면에서 이를 "무료 병렬 개발"로 해석하면 곤란합니다. "격리 기능 하나 때문에 오케스트레이션 도구를 샀다면 이제 그 도구를 하나 줄일 수 있다"고 보는 편이 정확합니다.

이 기능을 둘러싼 제품 전체를 살펴보려면 로컬 CLI와 에이전트 워크플로를 다룬 Codex 리뷰를 참고할 수 있습니다. 이전의 Codex CLI 0.152.0 해설은 터미널 자동화에서 릴리스별 제약을 확인해야 하는 이유를 보여 줍니다.

AI 코딩 에이전트와 함께 쓰기 좋은 워크트리 활용 사례 일곱 가지

1. 위험 부담이 큰 의존성 업그레이드

유지보수 담당자는 프레임워크, 패키지 관리자, 테스트 러너 업그레이드용 워크트리를 띄울 수 있습니다. Codex가 lockfile과 설정을 수정하고 전체 테스트 스위트를 실행하는 동안 메인 체크아웃에서 진행 중인 기능 작업은 흐트러지지 않습니다. 관련 없는 수정 사항을 stash하거나 되돌리지 않고도 버릴 수 있는, 검토 가능한 업그레이드 작업 공간을 얻는 것이 핵심 이점입니다.

2. 같은 기능을 서로 다른 방식으로 구현

테크 리드는 동일한 기획 대화를 두 개의 관리형 워크트리로 분기할 수 있습니다. 한 세션에는 가장 작은 패치를, 다른 세션에는 구조적인 접근을 요청한 뒤 diff 크기, 테스트, 마이그레이션 위험을 비교합니다. 두 번째 시도가 첫 번째 결과를 덮어쓰지 않으므로 근거를 바탕으로 방식을 선택할 수 있습니다.

3. 제품 개발을 계속하면서 버그 분류

기능 개발 도중인 제품 엔지니어도 커밋된 HEAD에서 깨끗한 워크트리를 열어 프로덕션 버그를 재현할 수 있습니다. Codex가 별도 작업 공간에서 계측하고 테스트하고 버그를 고치는 동안 완성되지 않은 기능은 그대로 남습니다. 긴급 stash가 줄고 핫픽스 diff도 더 깔끔해집니다.

4. 대규모 codemod와 리팩터링

플랫폼 팀은 광범위한 이름 변경이나 API 마이그레이션을 별도 체크아웃에 맡기고, 그곳에서 포매터와 테스트를 실행한 뒤 메인 브랜치에 들어오기 전에 변경 파일 전체를 검토할 수 있습니다. 자동 생성된 대량 변경을 커밋할 가치가 확인될 때까지 격리할 수 있다는 점이 이점입니다.

5. 리뷰 수정 전용 작업 공간

풀 리퀘스트 작성자는 리뷰 기준점을 커밋한 뒤 그 상태에서 격리된 Codex 세션을 시작해, 로컬의 다른 브랜치를 방해하지 않고 리뷰 의견을 반영할 수 있습니다. 준비가 되면 워크트리에서 바로 푸시할 수 있는 집중도 높은 수정 이력을 만들 수 있습니다.

6. 재현 가능한 유지보수 실행

빌드 엔지니어는 생성 파일 업데이트나 불안정한 테스트 조사처럼 범위가 뚜렷한 작업에 codex exec --worktree를 사용할 수 있습니다. 헤드리스 실행은 추적 파일이 깨끗한 체크아웃과 나중에 검사할 수 있는 영속 세션을 얻습니다. 기본 워킹 트리에 무엇이 열려 있든 우발적인 오염을 줄일 수 있습니다. 단, 자동화가 의존성 설정과 정리까지 책임져야 합니다.

7. 안전한 저장소 탐색

새 팀원은 평소 쓰는 체크아웃을 건드리기 전에 Codex로 낯선 코드베이스의 구조를 파악하고, 관리형 워크트리에서 작은 문서나 테스트 변경을 시험해 볼 수 있습니다. 심리적인 이점도 큽니다. 탐색 범위가 눈에 보이고, 마음에 들지 않으면 쉽게 버릴 수 있습니다.

이 빈틈에서 만들 만한 제품 세 가지

1. 가장 유망한 선택: 워크트리 실행 준비 계층

새 관리형 체크아웃을 실행 가능하고 충돌 없는 작업 공간으로 바꾸는 소형 로컬 툴을 만들 수 있습니다. 프로젝트 스택을 감지하고, 승인된 의존성 설정을 실행하고, 포트를 할당하고, 임시 데이터베이스나 스키마를 만들고, 선택한 시크릿만 노출하고, 상태 점검을 수행한 뒤 이에 맞는 정리 계획을 출력하는 도구입니다.

수요 기반은 넓습니다. git worktree의 미국 Google 월간 검색량은 약 9,900회이고, what is a git worktree도 590회입니다. Codex 기본 기능은 체크아웃 생성을 해결하지만 런타임 준비는 여전히 사용자 몫이므로, 이 아이디어가 가장 강력한 기회입니다.

판매 가능한 최소 버전에는 저장소 매니페스트, 설정 및 해제 명령, 포트 예약, 환경 파일 템플릿, 상태 점검이 필요합니다. 보안은 솔직히 짚어야 할 약점입니다. 시크릿을 복사하거나 두 에이전트가 같은 데이터베이스를 보게 하는 도구는 오히려 위험을 키울 수 있습니다. OpenAI가 수명 주기 훅을 기본 기능으로 추가해 이 틈을 줄일 가능성도 있습니다.

2. 여러 에이전트를 아우르는 작업 공간 대시보드

저장소와 툴 전반의 워크트리를 찾아내는 데스크톱 또는 터미널 대시보드를 만들 수 있습니다. 각 워크트리의 담당 세션, 브랜치 또는 detached 상태, 변경 파일, 테스트 결과, Codex 사용량, 풀 리퀘스트, 디스크 사용량을 보여 주고 안전한 재개 및 정리 동작을 제공하는 제품입니다.

git worktree claude code는 미국에서 월 약 480회 검색되고, 정확히 parallel coding agents라는 검색어는 10회입니다. 후자의 검색량은 작지만 유료 사용 의향은 이미 드러납니다. 병렬 에이전트 워크트리를 포함한 Unstoppable이 월 $19부터 시작하기 때문입니다. 구매자는 Codex, Claude Code, 일반 터미널을 함께 쓰며 작업을 조율하는 개발자입니다.

MVP는 읽기 전용으로 시작할 수 있습니다. Git 워크트리를 열거하고, 알려진 세션 메타데이터와 연결하고, 요청 시 상태 및 테스트 명령을 실행하고, 각 에이전트로 돌아가는 딥 링크를 제공하면 됩니다. 다만 기본 기능과 경쟁해야 합니다. Codex 0.154.0은 이미 자체 관리형 워크트리를 탐색하므로, 이 제품은 에이전트 간 통합 가시성, 런타임 상태, 팀 보고에서 앞서야 합니다.

3. 통합 및 정리 게이트

완료된 에이전트 작업 공간과 메인 브랜치 사이를 지키는 가드를 만들 수 있습니다. 깨끗한 상태인지 확인하고, 필수 테스트를 실행하고, 다른 활성 워크트리가 변경한 파일을 감지하고, cherry-pick 순서를 추천하며, 아직 통합하지 않은 커밋이 남아 있으면 파괴적인 정리를 거부하는 도구입니다.

실제 검색 수요에도 이런 질문이 보입니다. git remove worktree는 미국에서 월 약 390회, git worktree vs branch는 320회, git worktree prune은 140회 검색됩니다. 모두 격리된 작업을 공유 작업으로 옮기는 시점에 생기는 질문입니다.

MVP는 로컬 Git 명령과 작은 정책 파일만으로도 만들 수 있습니다. 코드 한 줄을 자동으로 수정하지 않아도 충분히 유용합니다. 다만 배포가 관건입니다. Git 클라이언트와 CI 공급자도 같은 검사를 추가할 수 있으므로, 독립 도구라면 여러 코딩 에이전트와 복잡한 실제 저장소를 탁월하게 지원해야 합니다.

도입 결정을 좌우하는 한계

파일 격리가 문제일 때 기본 워크트리를 사용해야 합니다. 완전한 환경 격리 수단으로 오해해서는 안 됩니다.

이번 릴리스에는 Desktop 앱의 Handoff 버튼에 해당하는 CLI 기능도 없습니다. 코드를 원래 작업 공간으로 가져오는 일은 여전히 Git 차원의 결정입니다. 커밋 후 cherry-pick하거나, 브랜치를 푸시하거나, 결과를 버리고 제거해야 합니다. 이런 명시적인 단계는 오히려 바람직합니다. 원치 않는 변경이 메인 체크아웃으로 흘러들지 않는 것이 격리의 목적이기 때문입니다.

이번 주에 바로 해볼 일입니다. 중요도가 낮은 의존성 업데이트 하나를 골라 codex --enable worktrees --worktree로 실행하고, 복사한 체크아웃 경로에서 diff와 테스트 결과를 비교합니다. 채택할 커밋만 cherry-pick한 뒤 워크트리를 제거합니다. 저장소에 맞는 안정적인 격리 에이전트 워크플로가 필요하다면 프로덕션 시스템 설계를 도와드리겠습니다.