Sessions와 Worktrees

기준일: 2026-07-26
난이도: 중급
공식 기준: Manage sessions, Run parallel sessions with worktrees

세션은 프로젝트 디렉터리에 묶인 저장된 대화입니다. Worktree는 같은 저장소 안에서 파일 편집이 충돌하지 않도록 분리된 체크아웃입니다. 병렬 작업은 worktree로 파일을 가두고, 서브에이전트·에이전트 팀으로 역할을 나눕니다.

이 페이지는 CLI 세션 저장소를 다룹니다. Desktop / web / VS Code는 각각 별도 히스토리를 가집니다.

핵심 개념

세션

진입점	동작
claude --continue	현재 디렉터리의 가장 최근 세션
claude --resume	세션 picker
claude --resume <name>	이름(또는 session ID)으로 직접 재개
claude --from-pr <number>	해당 PR에 연결된 세션으로 필터
/resume	활성 세션 안에서 다른 대화로 전환

claude -p / Agent SDK 세션은 picker에 안 보일 수 있으나 claude --resume <session-id>로 재개 가능(시작했던 프로젝트 디렉터리·worktree 범위에서 조회).

재개 시 복원: 대화·도구 결과, 모델(일부 제약 시 제외), agent 설정, permission mode(plan·bypassPermissions는 복원 안 함; auto는 계정 요건 충족 시), 활성 goal(카운터·타이머 리셋), 만료되지 않은 scheduled tasks.

재개 시 다시 넘겨야 할 수 있음: --mcp-config, --settings, --plugin-dir, --fallback-model, --add-dir 등. settings.json 계열은 재-read.

이름 지정

시점	방법
시작	claude -n auth-refactor
중	/rename auth-refactor
picker	세션 강조 후 Ctrl+R
plan 수락	이미 이름을 안 붙였으면 plan 내용으로 자동 명명

이름 없는 인터랙티브 세션은 v2.1.196+ 기본 display name(디렉터리+접미사)을 받지만, 이는 resume handle이 아닙니다. AI 생성 title도 picker 표시용이지 claude --resume <name> 대상이 아닙니다.

Worktree

claude --worktree feature-auth
# 단축: -w

• 기본 경로: 저장소 루트 .claude/worktrees/<name>/
• 기본 브랜치 이름: worktree-<name>
• 이름 생략 시 자동 생성(예: bright-running-fox)
• interactive는 workspace trust 필요. 미신뢰 시 --worktree는 오류. -p는 trust 스킵
• .claude/worktrees/를 .gitignore에 추가 권장

세션 중 "work in a worktree" 요청 시 EnterWorktree 도구 사용. 저장소 밖 경로로 들어가면 승인 필요(bypassPermissions만 예외).

선택 기준

상황	추천
어제 작업 이어하기	--continue / --resume
같은 대화에서 다른 접근 실험	/branch 또는 --fork-session
기능 A와 버그 B를 동시에 파일 수정	각각 --worktree
서브에이전트 병렬 편집	subagent frontmatter isolation: worktree
체크포인트로 되돌리기	Checkpointing (fork와 다름)

실습

세션 분기

/branch try-streaming-approach

claude --continue --fork-session

/branch는 transcript를 복사하고 같은 프로세스에서 쓰므로 세션 내 "Allow for this session" 승인이 유지됩니다. --fork-session은 별도 프로세스라 재승인할 수 있습니다. 포크 없이 같은 세션을 두 터미널에서 resume하면 transcript가 섞입니다.

컨텍스트 관리

• /clear — 빈 컨텍스트(이전 대화는 저장, /resume 가능). 설정한 이름은 유지
• /compact [instructions] — 요약으로 교체
• /context — 컨텍스트 소비 현황

내보내기·저장 위치

• /export — 클립보드 또는 텍스트 파일
• 기본 transcript: ~/.claude/projects/<project>/<session-id>.jsonl (경로 비영숫자 → -)
• 스크립트: claude -p --output-format json, hooks의 transcript_path, Agent SDK
• 보존: cleanupPeriodDays, CLAUDE_CONFIG_DIR, CLAUDE_CODE_SKIP_PROMPT_HISTORY, -p의 --no-session-persistence

Worktree 정리

interactive 종료 시: clean이면 unnamed은 자동 제거, named는 확인. 변경이 있으면 keep/remove 프롬프트. -p는 자동 cleanup 없음 → git worktree remove.

서브에이전트·background session worktree는 cleanupPeriodDays 이후 주기 sweep(작업 중이면 유지). --worktree로 만든 것은 sweep 대상 아님.

커스터마이즈

{
  "worktree": {
    "baseRef": "head"
  }
}

• "fresh" (기본): remote 기본 브랜치 기준
• "head": 현재 로컬 HEAD (진행 중 작업을 subagent isolation에 실을 때)

PR 기준:

claude --worktree "#1234"

gitignored 파일 복사: 프로젝트 루트 .worktreeinclude (gitignore 문법, gitignored 파일만 복사).

.env
.env.local

수동 worktree:

git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a
claude

비-git VCS: hooks WorktreeCreate / WorktreeRemove로 대체.

공유되는 것

Worktree는 파일·브랜치는 분리하되 .git, project-scope 플러그인, 영구 Bash 승인(v2.1.211+ 메인 checkout .claude/settings.local.json에 저장)을 공유합니다.

picker 단축키 (요약)

↑↓ 이동, Enter 재개, Space 미리보기, Ctrl+R 이름, / 검색, Ctrl+W 저장소 worktree 전체, Ctrl+A 머신 전 프로젝트, Ctrl+B 현재 git 브랜치 필터.

체크리스트

• 병렬 파일 수정 전에 worktree 또는 subagent isolation: worktree를 정했다.
• .claude/worktrees/를 ignore했고 필요 시 .worktreeinclude를 넣었다.
• 장기 작업 세션에 /rename 또는 -n을 붙였다.
• resume 시 복원되지 않는 플래그·bypassPermissions를 다시 넘겼다.
• 끝난 worktree를 정리했다 (git worktree list / remove).

다음 단계

• Agent view — 백그라운드 세션과 파일 격리
• 서브에이전트 — worktree isolation frontmatter
• 체크포인팅 — 세션 내 rewind
• 헤드리스 모드 — -p와 session ID