세션 관리하기

세션 관리하기

Claude Code 대화는 프로젝트 디렉토리에 묶여 로컬에 저장되는 세션(session) 단위로 관리됩니다. 세션에 이름을 붙이고, 재개(resume)하고, 분기(branch)하고, 전환하며, 트랜스크립트를 내보내거나 그 위치를 확인하는 방법을 다룹니다. --continue, --resume, --from-pr, /resume 피커, 세션 이름 지정, 트랜스크립트 내보내기·저장 위치까지 한 권에 담았습니다.

출처: 공식문서

본문

세션 재개 (Resume a session)

세션은 작업 중 로컬 트랜스크립트 파일에 계속 저장되므로, 종료하거나 /clear하더라도 돌아갈 수 있습니다.

claude -p(headless)나 Agent SDK로 만든 세션은 피커에 표시되지 않지만, 세션 ID를 claude --resume <session-id>로 넘기면 재개할 수 있습니다. claude --resume <session-id>는 어느 디렉토리에서든 실행 가능하며, 먼저 현재 프로젝트와 git worktree에서 찾은 뒤 이 머신의 다른 모든 프로젝트에서 찾습니다.

재개 시 복원되는 것:

• 대화 히스토리: 도구 호출·결과 포함 전체. 이전 종료 시 실행 중이던 도구는 재개 시 다시 실행되지 않음
• 모델: 세션 사용 중이던 모델 유지(은퇴했거나 availableModels/--model/ANTHROPIC_MODEL 계열 env로 선택되는 경우 등은 미복원)
• 에이전트: --agent 또는 agent 설정으로 시작한 세션은 그 에이전트로 계속(도구 제한·모델 유지). --agent를 넘기면 다른 에이전트 선택 가능
• 권한 모드: 터미널에서 재개하면 보통 세션이 있던 권한 모드 복원. --permission-mode나 --dangerously-skip-permissions로 오버라이드
• 활성 목표(goal): 세션 종료 시 활성 상태였던 goal은 이어짐(턴 카운트·타이머·토큰 기준은 리셋)
• 예약 작업: 만료되지 않은 작업 복원. 백그라운드 Bash·모니터 작업은 미복원

--mcp-config, --settings, --plugin-dir, --fallback-model, --add-dir 등 일부 구성 플래그는 재개 시 다시 넘겨야 합니다. 표준 설정 파일(settings.json 등)은 재개 시 재읽히므로 다시 넘길 필요가 없습니다.

권한 모드 on resume 표: 터미널 경로는 세션이 있던 권한 모드를 복원(예외: bypassPermissions는 다시 활성화 필요, auto는 계정 요건 충족 시에만, plan은 새 세션 모드). 피커·/resume·claude -p 경로는 저장된 권한 모드를 복원하지 않고 새 세션 시작 모드를 사용합니다. claude -p --resume/--continue가 plan 모드로 재개되려면 ① --permission-prompt-tool 전달 ② --permission-mode/--dangerously-skip-permissions 미전달 ③ --fork-session 미전달 ④ channels로 시작 안 함 — 4가지가 모두 충족돼야 합니다 (v2.1.246+).

요약부터 재개 (Resume from summary): Pro/Max 플랜에서 1시간 넘게 비활성·100,000 토큰 초과 세션을 재개하면 대화 상자가 열립니다. 옵션은 ① Resume from summary(즉시 /compact 실행, 요약 전송 후 히스토리 대체) ② Resume full session as-is(대화 그대로, 이후 요청이 전체 히스토리를 재처리·재캐시) ③ Don't ask me again(앞으로 표시 안 함). 요약 재개는 요청당 비용은 줄지만 요약에서 빠진 상세는 컨텍스트에서 사라집니다.

피커가 보는 곳: 기본적으로 현재 워크트리의 세션(bg 표시의 백그라운드 세션 포함)과 /add-dir로 추가된 디렉토리의 세션. Ctrl+W로 저장소의 모든 워크트리, Ctrl+A로 이 머신의 모든 프로젝트로 확대. 첫 프롬프트가 /loop인 세션은 피커에 나타나지 않습니다.

세션 이름 지정 (Name your sessions)

• 시작 시: claude -n auth-refactor
• 세션 중: /rename auth-refactor (프롬프트 바에 표시)
• 피커에서: 세션 강조 후 Ctrl+R
• plan 수락 시: 이미 이름을 안 지었다면 계획 기반 제목 부여

이름이 이미 다른 라이브 세션과 충돌하면 두 단어 접미사를 붙여(auth-refactor-graceful-unicorn) 알려줍니다. 이름 없는 세션에는 기본 표시 이름(디렉토리명+2자 접미사, 예: my-app-3f)과 생성 제목(첫 프롬프트 요약, Haiku급 소형 모델이 백그라운드로 작성)이 붙는데, resume 핸들로 동작하는 것은 생성 제목뿐입니다.

세션 피커 사용

/resume 또는 claude --resume로 피커를 엽니다. 단축키: ↑/↓ 이동, →/← 그룹 펼침/접기, Enter 재개, Space 미리보기, Ctrl+R 이름 변경, / 검색(PR URL 붙여넣기로 생성한 세션 찾기), Ctrl+A 전 프로젝트, Ctrl+W 전 워크트리, Ctrl+B 현재 브랜치 필터, Esc 종료. /branch나 --fork-session 세션은 자체 세션 ID를 가지며, 같은 세션의 여러 항목은 하나의 행으로 그룹화됩니다.

세션 분기 (Branch a session)

분기는 지금까지의 대화 복사본을 만들어 그 안으로 전환하고 원본은 그대로 둡니다.

/branch try-streaming-approach

명령줄에서는 --continue --fork-session 조합을 사용합니다:

claude --continue --fork-session

/branch는 트랜스크립트를 복사하고 실행 중인 프로세스가 그쪽에 쓰도록 전환합니다. 대화 히스토리는 복사되고, "이 세션 허용" 권한은 이어지며(--fork-session으로 별도 프로세스면 재승인 필요), 진행 중인 백그라운드 서브에이전트·Bash 명령은 계속 실행돼 새 브랜치에 출력이 나타납니다.

세션 내 컨텍스트 관리

• /clear — 빈 컨텍스트로 새 출발 (이전 대화는 저장됨). 인자 없으면 --name//rename 이름은 유지하되 AI 생성 제목은 버림
• /compact [instructions] — 히스토리를 요약으로 대체, 선택적 초점 지정
• /context — 현재 컨텍스트를 소비 중인 항목 표시

세션 데이터 내보내기·찾기

/export로 현재 대화를 클립보드에 복사하거나 평문 파일로 저장하고, 파일명을 넘기면 메뉴 없이 직접 씁니다. 스크립트에서 쓰려면:

• 결과 캡처: claude -p를 --output-format json 또는 stream-json과 함께 실행
• 기존 세션에 질문: claude -p --resume <session-id>로 후속 프롬프트 전송
• 이벤트 반응: 훅·상태줄이 받는 transcript_path 필드 읽기 (SessionEnd 훅으로 아카이브)
• 앱 임베드: TypeScript/Python용 Agent SDK 사용

claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

트랜스크립트 저장 위치: 기본값 ~/.claude/projects/<project>/<session-id>.jsonl. <project>는 작업 디렉토리 경로에서 비영숫자 문자를 -로 바꾼 이름입니다. 200자를 넘으면 잘라내고 전체 경로 해시를 붙입니다. 각 줄은 메시지·도구 사용·메타데이터용 JSON 객체이며, 형식은 내부 전용이라 버전 간 바뀔 수 있습니다(직접 파싱 대신 /export나 스크립트 인터페이스 권장).

설정 가능 항목: CLAUDE_CONFIG_DIR(저장 위치 이동), CLAUDE_CODE_PROJECT_DIR_NAME(프로젝트 디렉토리명 직접 지정), cleanupPeriodDays(30일 보존 변경), CLAUDE_CODE_SKIP_PROMPT_HISTORY(전 모드 기록 억제), --no-session-persistence(비대화형 1회 억제).

이름 직접 지정하기: CLAUDE_CODE_PROJECT_DIR_NAME을 CLAUDE_CONFIG_DIR과 함께 설정하면 세션 트랜스크립트·auto memory를 사용자 이름 아래에 저장합니다. 예:

CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude

이 경우 트랜스크립트는 /srv/tenant-a/projects/work/, auto memory는 /srv/tenant-a/projects/work/memory/에 기록됩니다. 규칙: ① CLAUDE_CONFIG_DIR도 반드시 설정(기본 ~/.claude에서는 모든 프로젝트가 한 곳으로 합쳐짐, 미설정 시 무시) ② 1~64자의 영문·숫자·하이픈·밑줄 ③ claude를 시작하는 셸 환경에서 설정(settings 파일의 env 블록으로는 불가).

더 알아보기

• Worktrees — 별도 브랜치에서 격리 병렬 세션 실행
• Checkpointing — 코드·대화를 이전 지점으로 되감기
• 컨텍스트 창 — 무엇이 채우고 무엇이 통합을 견디나
• 비대화형 모드 — claude -p