이 도구의 기능

claude-file-recovery는 Claude Code의 세션 기록에서 파일을 추출하는 Python 명령줄 도구로, 대화형 TUI를 제공합니다. 이 도구는 작성자가 Claude Code가 인식하지 못하는 심볼릭 링크를 통해 파일을 실수로 삭제했고, 백업이 한 달 동안 실행되지 않았던 사건 이후 만들어졌습니다. 이 도구는 ~/.claude/projects/에 저장된 JSONL 세션 기록을 파싱하여 파일을 재구성합니다.

주요 기능

이 도구는 Claude Code가 읽거나 편집했거나 작성한 모든 파일을 복구할 수 있으며, 특정 시점의 파일 이전 버전도 포함합니다. 제공하는 기능은 다음과 같습니다:

• 퍼지 검색과 vim 키 바인딩(j/k/g/G, /로 검색)을 지원하는 대화형 TUI
• 특정 시점 복구 — 최신 버전뿐만 아니라 모든 과거 스냅샷에서 파일 재구성
• 파일이 시간에 따라 어떻게 변경되었는지 보여주는 색상 구분 diff 뷰(통합, 전체 컨텍스트, 원본 모드)
• 일괄 추출 — 여러 파일을 선택하여 한 번에 모두 추출
• 빠른 스캔 — orjson과 파싱 전 약 77%의 라인을 건너뛰는 빠른 거부 바이트 검사를 통한 병렬 세션 파싱
• 심볼릭 링크 중복 제거 — 별칭 경로를 감지하고 표준 항목으로 병합
• 스마트 케이스 검색 — 쿼리에 대문자가 포함된 경우에만 대소문자 구분(ripgrep과 유사)

설치 및 사용법

Python 3.10+가 필요합니다. 설치 옵션:

# 권장
uv tool install claude-file-recovery

또는 pipx 사용
pipx install claude-file-recovery
또는 pip 사용
pip install claude-file-recovery

기본 명령어:

# 대화형 TUI 실행 (기본 명령)
claude-file-recovery

복구 가능한 모든 파일 나열
claude-file-recovery list-files
패턴으로 필터링
claude-file-recovery list-files --filter '*.py'
CSV로 내보내기
claude-file-recovery list-files --filter '*.ts' --csv
파일을 디스크로 추출
claude-file-recovery extract-files --output ./recovered --filter '*.py'
특정 시간 이전의 파일 상태 복구
claude-file-recovery list-files --before '2025-02-20 14:00'
다른 Claude 데이터 디렉토리 지정
claude-file-recovery --claude-dir /path/to/claude-backup

작동 원리

이 도구는 ~/.claude/projects/ 아래의 모든 JSONL 세션 파일을 스캔하고 스레드 풀을 사용하여 병렬로 파싱합니다. tool_use_id를 통해 어시스턴트 메시지의 도구 사용 요청을 사용자 메시지의 결과와 연결한 다음, 파일 경로별로 시간순으로 작업을 재생하여 파일을 재구성합니다: 쓰기 작업은 내용을 설정하고, 편집 작업은 문자열 교체를 적용하며, 읽기 작업은 스냅샷을 캡처합니다. --before 플래그는 이진 검색을 사용하여 특정 시점에서 작업을 중단합니다.

TUI 키 바인딩

• j/k: 위/아래로 이동
• g/G: 맨 위/맨 아래로 이동
• /: 검색
• Ctrl+R: 검색 모드 순환 (퍼지 / 글로브 / 정규식)
• x 또는 Space: 파일 선택 토글
• Enter: 파일 상세 정보 + diff 보기
• d: diff 모드 순환 (통합 / 전체 컨텍스트 / 원본)
• Ctrl+E: 선택한 파일 추출
• q: 뒤로 / 종료

이러한 복구 도구는 Claude Code를 광범위하게 사용하는 개발자들이 실수로 파일을 삭제하거나 손상시키는 경우에 대비하는 데 유용합니다. MIT 라이선스 프로젝트는 작성 시점 기준으로 GitHub에서 26개의 스타와 1개의 포크를 보유하고 있습니다.