CLI. claude project purge
특정 프로젝트의 로컬 Claude Code 상태를 안전하게 삭제하는 CLI 서브커맨드
핵심 요약
claude project purge는 슬래시 명령이 아니라 셸에서 실행하는 CLI 서브커맨드로, 한 프로젝트의 로컬 Claude Code 상태를 삭제한다.- transcript·auto memory, 세션별 tasks/debug/file-history,
history.jsonl의 일치 prompt 라인,~/.claude.jsonentry를 정리한다. - 삭제 전 전체 deletion plan을 출력하고 확인을 요청하며,
--dry-run으로 대상을 미리 보고-y로 프롬프트를 건너뛴다. --all은 path 필터 없이history.jsonl을 통째로 삭제하므로 공유 장비·계정에서는 path를 명시하고 사용을 피한다.- v2.1.126 이상에서 제공되며,
shell-snapshots/·backups/와 auth·설정·플러그인 파일은 건드리지 않는다.
명령어 원본 선언
claude project purge [path]/project-purge 형태의 슬래시 명령이 아니라 터미널에서 실행하는 CLI 서브커맨드입니다. 세션 안에서 /로 호출하지 말고 셸에서 claude project purge로 바로 실행하세요.
공식 설명 요약
claude project purge는 한 프로젝트를 두고 Claude Code가 보관 중인 모든 로컬 상태를 삭제하는 CLI 서브커맨드입니다. 공식 문서 기준으로 다음 항목을 정리합니다.
projects/아래의 transcript와 auto memory- 세션별
tasks/,debug/,file-history/엔트리 history.jsonl에서 해당 프로젝트와 일치하는 prompt 라인~/.claude.json에 있는 해당 프로젝트의 entry
명령은 삭제하기 전에 전체 삭제 계획(deletion plan)을 출력하고 확인을 요청합니다. [path]를 생략하면 대화형 목록에서 프로젝트를 선택할 수 있습니다.
최소 지원 버전
v2.1.126이상 (공식 Changelog, 2026-05-01 릴리스에서 추가)
사용법
삭제하지 않고 계획만 미리 보기:
claude project purge ~/work/repo --dry-run단일 확인 프롬프트와 함께 삭제:
claude project purge ~/work/repo스크립트에서 확인 프롬프트 없이 삭제:
claude project purge ~/work/repo --yes모든 프로젝트 상태를 한 번에 정리(미리보기 권장):
claude project purge --all --dry-run주요 옵션
| 옵션 | 목적 |
|---|---|
--dry-run | 실제 삭제 전 삭제 대상 미리보기 |
-y, --yes | 확인 프롬프트 생략 (스크립트용) |
-i, --interactive | 삭제 계획을 항목별로 하나씩 확인 |
--all | path 대신 사용해 모든 프로젝트 상태 삭제 |
좋은 사용 예
- 민감 repository 작업 후 로컬 대화/디버그 흔적 정리
- 깨진 session/task 상태 때문에
/resume이 불안정할 때 상태 재설정 - 장비 반납 전 프로젝트별 Claude Code state 삭제
비슷한 명령어 추천
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
claude project purge | 로컬 프로젝트 상태 삭제 | transcript/state 정리 |
/clear | 현재 대화 시작점 초기화 | 같은 세션에서 새 대화 시작 |
/rewind | 대화/코드 이전 지점으로 복귀 | 특정 변경 되돌리기 |
/resume | 저장된 이전 세션 재개 | 유지해야 할 state가 있을 때 |
활용 사례
- 대상 미리 확인: 먼저
--dry-run으로 삭제 계획을 출력해 어떤 transcript·task·history 라인이 지워질지 확인한 다음 실제 실행으로 넘어갑니다. - 전체 정리와 부분 정리 구분:
--all은 path 기반 필터링과 달리history.jsonl을 통째로 삭제합니다. 특정 프로젝트만 정리하려면 path를 명시하세요. - 항목별 검토:
-i(--interactive)로 삭제 계획을 한 항목씩 넘기며 선택적으로 지울 수 있습니다.
주의사항
- 삭제성 명령이므로 먼저
--dry-run으로 대상 범위를 확인하세요. - 팀 장비나 공유 계정에서는 project path를 명시하고
--all사용을 피하세요.--all은history.jsonl을 필터링 없이 통째로 삭제합니다. shell-snapshots/와backups/는 프로젝트 범위가 아니므로 건드리지 않으며, 계획 출력에서 경고만 표시합니다.- 주어진 path에 일치하는 상태가 없으면 명령은 status 1로 종료합니다.
- transcript가 필요한 감사/인수인계 상황에서는 export나 백업 정책을 먼저 확인하세요.
~/.claude.json,~/.claude/settings.json,~/.claude/plugins/는 auth·환경설정·설치된 플러그인을 담고 있으므로 직접 삭제하지 마세요.
출처
- CLI reference: https://code.claude.com/docs/en/cli-reference
- Clear local data: https://code.claude.com/docs/en/claude-directory#clear-local-data
- Changelog: https://code.claude.com/docs/en/changelog