Cmd. /worktree
0.156.0부터 기본 활성화된 worktree 세션으로 새 세션·fork를 격리 git checkout에서 실행하는 방법을 설명합니다.
핵심 요약
- 0.156.0부터 기본 활성화된 worktree 세션으로 새 세션·fork를 격리 git checkout에서 실행하는 방법을 설명합니다.
/worktree나codex --worktree로 시작하면 작업이 별도 checkout에서 진행되며, 0.162.0부터는 Codex가 managed worktree를 직접 만들고 조회합니다.
역할
0.156.0부터 기본 활성화된 worktree 세션으로 새 세션·fork를 격리 git checkout에서 실행하는 방법을 설명합니다.
/worktree사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 현재 공식 표 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-10-23 · Codex CLI 0.163.0 |
| 릴리스 근거 | v0.156.0 |
0.154.0에 실험 기능으로 추가됐고 0.156.0부터 기본 활성화됐습니다. Git 저장소가 필요하며 agent command center에서도 worktree 세션을 만들 수 있습니다.
사용 예
/worktree/worktree와 CLI의 --worktree는 worktree 세션 흐름을 제공합니다. 0.154.0에 실험 기능으로 들어왔고 0.156.0부터 기본 활성화됐습니다. 새 작업이나 fork를 별도 checkout으로 분리하고 해당 세션을 탐색·재개할 수 있습니다.
codex --worktree기존 작업의 branch와 checkout 위치를 확인한 뒤 격리 세션을 시작하세요. 0.155.0의 agents 화면은 worktree 소유 정보를 보여주고, 관리되는 clean worktree를 삭제할 때 확인을 받습니다. archive와 worktree 삭제는 같은 작업이 아니므로 세션 기록과 파일 보존을 각각 확인합니다. 0.156.0부터 agent command center에서 상태별로 작업을 거르고 worktree 세션을 바로 만들 수 있습니다.
0.162.0은 worktrees 기능이 켜진 신뢰된 로컬 프로젝트에서 Codex가 managed Git worktree를 만들고 조회하는 도구를 추가했습니다. PR 설명에 따르면 도구는 create_worktree·get_worktree_creation_status·list_worktrees이고, worktree는 비동기로 만들어져 요청한 task에 연결됩니다. ref를 주지 않으면 저장소 remote의 기본 브랜치에서 시작합니다. task의 작업 디렉터리와 원본 checkout의 커밋하지 않은 변경은 그대로 남고, 임시 side conversation이나 신뢰하지 않은 프로젝트에서는 생성이 거부됩니다.
더 자세한 흐름은 세션 수명주기를 참고하세요.
실행 결과와 유지 범위
별도의 Git worktree에서 새 작업을 시작하거나 대화를 분기합니다. 새 checkout의 경로와 브랜치를 확인합니다.
주의사항
0.154.0에 실험 기능으로 추가됐고 0.156.0부터 기본 활성화됐습니다. Git 저장소가 필요하며 agent command center에서도 worktree 세션을 만들 수 있습니다.
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록