Claude Code 모든 세션을 한 곳에서 관리하기: claude-sessions 공개

왜 필요했는가

Claude Code를 몇 주만 써보면 다음과 같은 상황을 한두 번은 겪는다.

• “그 검색 기능 관련해서 한 달 전쯤 길게 대화했었는데… 어디서 했더라?”
• “분명 A 프로젝트 폴더에서 리팩터링 논의했는데 /resume에 안 뜬다. 다른 폴더에서 시작했었나?”
• “서브에이전트가 Task 도구로 뭘 했는지 다시 보고 싶은데 부모 세션 메시지에는 결과만 요약돼 있다.”

원인은 Claude Code의 저장 구조에 있다. 세션은 ~/.claude/projects/<인코딩된-cwd>/<세션-id>.jsonl 경로에 저장되고, 내장 /resume 메뉴는 현재 작업 폴더에 해당하는 인코딩 디렉터리에 속한 세션만 보여준다. 프로젝트별로 분리해주는 의도는 좋지만, 전체 세션을 한눈에 훑고 싶거나 “X를 작업했던 그 대화”를 키워드로 찾고 싶을 때는 쓸 방법이 없다.

필요했던 것은 단순했다. 로컬 디스크의 모든 세션을 한 곳에서 검색·열람하고, 선택한 세션을 원래 작업 폴더에서 바로 이어갈 수 있는 도구. 이왕 만들 거면 오래된 세션은 아카이브해서 자리를 줄이고, 백업에서 복원할 수 있고, “A 폴더에서 claude를 켰지만 실제 작업은 B 폴더에서 했던” 상황도 고쳐주는 도구로 만들자는 것이 claude-sessions다.

어떻게 동작하는가

설계 원칙은 세 가지였다: ① 의존성 제로 — Python 표준 라이브러리만, ② 빠른 반응성 — 캐시로 콜드/웜 실행을 분리, ③ 파괴적 동작은 항상 확인.

첫 실행 때만 ~/.claude/projects/**/*.jsonl 전체를 한 번 읽어 세션별 메타(시작/마지막 시각, 메시지 수, 첫 사용자 메시지, 원본 cwd 등)를 뽑아 캐시에 쓴다. 다음 실행부터는 파일의 mtime과 size가 그대로면 캐시에서 즉시 복원한다. 실측치로 86개 세션 기준 콜드 7.7초 → 웜 0.18초(약 40배)였다.

캐시는 인덱스만 담는다. search나 show처럼 본문을 다루는 명령은 매번 원본 JSONL을 파싱한다. 캐시 자체가 깨져도 다음 실행에서 자동으로 재구축되도록 설계했고, 필요하면 그냥 파일 한 개를 지우면 된다.

주요 기능

서브커맨드	하는 일
pick (기본)	curses TUI. 라이브 필터 · Space 멀티선택 · Del 삭제 · Enter로 cd + claude --resume
list	최근순 테이블. --limit, --cwd, --days
search	사용자·어시스턴트 본문 전체 검색. -i, |로 OR
show	세션 트랜스크립트 출력. --with-subagents로 서브에이전트 포함
subagents	부모 세션이 디스패치한 모든 Task 서브에이전트 목록 (타입·설명·첫 프롬프트)
resume	cd <cwd> && claude --resume <id> 한 줄 생성
backup	오래된 세션을 tar.gz로 아카이브(+manifest.json). --delete로 원본 제거
restore	백업 복원. skip/overwrite/rename 충돌 정책
relocate	세션의 cwd 재지정 + 파일 이동 (A에서 시작했는데 B에서 작업한 케이스)
stats	프로젝트별 세션·메시지 통계

인터랙티브 피커

claude-sessions를 인자 없이 실행하면 curses TUI가 뜬다. 화면은 대략 이런 모습이다.

 claude-sessions v0.1.0  86/86   ↑↓ move  PgUp/PgDn page  Enter open  Space mark  Del delete  Esc quit
>
   LAST ACTIVITY     SESSION      MSGS  MESSAGE
 ● 2026-04-11 15:41  f6b0b565   [  42]  로컬 시스템에서 작업했던 모든 세션 목록을…
   2026-04-11 15:40  125ac1ac   [ 416]  biz-plan-harness 스킬을 이용해서 "…
   2026-04-11 15:26  f6e7aced   [ 202]  생성할 콘텐츠는 레벨…
 📁  ~/.claude/skills

위쪽에 버전과 키바인딩 힌트, 그 아래 필터 입력란, 그리고 LAST ACTIVITY · SESSION · MSGS · MESSAGE 네 컬럼의 목록이 뜬다. 화살표로 커서를 움직이면 푸터에 해당 세션의 원본 폴더가 표시되어 “이게 어느 프로젝트였지?”가 바로 확인된다. 타이핑하면 세션 id, 폴더, 첫 사용자 메시지 전체를 대상으로 라이브 필터가 걸린다.

검색 · 서브에이전트 열람

search는 사용자와 어시스턴트 메시지의 텍스트 블록을 통째로 훑어 매칭 스니펫을 보여준다. 파이프 |로 간단한 OR 질의도 된다.

claude-sessions search "rate limiter" -i --limit 20
claude-sessions search "nextjs|remix" --cwd ~/project

그리고 의외로 유용했던 것이 서브에이전트 열람이다. Claude Code에서 Task 도구로 병렬 리서치나 서브태스크를 돌리면 그 서브에이전트의 전체 대화가 ~/.claude/projects/<cwd>/<parent-id>/subagents/agent-<hex>.jsonl에 따로 저장된다. 부모 세션에는 도구 결과만 요약돼 남기 때문에, 서브에이전트가 실제로 무슨 질문에 무슨 답을 했는지는 이 파일을 직접 봐야 알 수 있다.

# 부모 세션의 서브에이전트 목록
claude-sessions subagents 125ac1ac

# 특정 서브에이전트만 단독 열람 (prefix 매칭)
claude-sessions show agent-ae71057b7264de3db

# 부모 트랜스크립트 + 모든 서브에이전트 전문을 한 번에
claude-sessions show 125ac1ac --with-subagents

백업 · 복원 · Relocate

backup은 오래된 세션을 한 뭉텅이로 tar.gz에 담는다. 아카이브 최상단에는 manifest.json이 함께 기록되어 “이 백업은 언제 만들어졌고, 어떤 세션이, 어느 프로젝트 폴더에서, 몇 개 메시지로 끝났는지”를 복원 전에 미리 확인할 수 있다.

# 90일 넘은 세션을 계획만 미리보기
claude-sessions backup --days 90 --dry-run

# 아카이브 + 원본 삭제 (백업 성공해야만 삭제)
claude-sessions backup --days 90 --delete

# 복원 (기존 파일과 충돌하면 기본은 skip)
claude-sessions restore ~/.claude/backups/sessions-20260411-153000.tar.gz
claude-sessions restore <archive> --on-conflict rename

relocate는 개인적으로 가장 만족하는 기능이다. Claude Code를 “임시 폴더”나 홈 디렉터리에서 켰지만 Bash 도구로 이동해서 실제로는 다른 프로젝트에서 작업한 경우, 세션이 엉뚱한 cwd에 매여 있어서 나중에 --resume으로 돌아가면 어색해진다. relocate는 JSONL 이벤트의 모든 cwd 필드를 재작성하고 파일을 새 프로젝트 디렉터리로 물리 이동하여 이 어긋남을 고친다. 서브에이전트 디렉터리도 같이 이동하고, 쓰기는 .tmp → atomic rename 방식이라 중간 실패가 원본을 망가뜨리지 않는다.

# 미리보기
claude-sessions relocate f6b0b565 ~/project/actual-work --dry-run

# 실행 (확인 프롬프트)
claude-sessions relocate f6b0b565 ~/project/actual-work

# 원본도 남기고 새 경로로 복사만
claude-sessions relocate f6b0b565 ~/project/actual-work --keep-original

설치 · 사용

Python 3.9 이상이면 끝이다. pip install이 없다.

# 1. clone
git clone https://github.com/greeun/claude-sessions ~/.claude/skills/claude-sessions

# 2. 실행 권한 + PATH 심볼릭 링크
chmod +x ~/.claude/skills/claude-sessions/sessions.py
mkdir -p ~/.local/bin
ln -sf ~/.claude/skills/claude-sessions/sessions.py ~/.local/bin/claude-sessions

# 3. 확인
claude-sessions --version
# claude-sessions v0.1.0

# (선택) 짧은 alias
echo "alias cs='claude-sessions'" >> ~/.zshrc && source ~/.zshrc
cs                          # 피커 열기
cs search "migration" -i    # 키워드 검색
cs list --days 7            # 최근 7일

안전하게 만드는 것

세션 기록은 개발자에게 꽤 귀중한 자산이다. 몇 주/몇 달 전의 설계 결정, 디버깅 과정, 대화형 리팩터링이 전부 여기 들어 있다. 그래서 파괴적 명령은 모두 다음 원칙을 지킨다.

• 기본 읽기 전용 — list, search, show, stats, resume, subagents는 어떤 파일도 수정하지 않는다.
• 피커 삭제는 모달 확인 — Space 마크 후 Del을 누르면 화면 중앙에 삭제 대상 목록이 뜨는 confirmation 모달이 나타나고, y/N을 받아서야 unlink한다.
• CLI는 dry-run 우선 — backup, restore, relocate 모두 --dry-run으로 계획을 먼저 볼 수 있다. 확인 프롬프트는 기본이고 -y로 스킵한다.
• Atomic write — relocate는 새 파일을 .tmp로 쓰고 성공 시 replace()로 교체한다. 중간에 프로세스가 죽어도 원본은 온전하다.
• 가역적 backup — --delete를 명시하기 전까지 원본은 그대로 남는다. 일부 파일이 아카이브에 실패하면 --force 없이는 원본 삭제를 거부한다.

마무리

처음엔 “세션 목록 좀 보는 스크립트” 하나면 충분하다고 생각했다. 막상 쓰다 보니 검색이 필요했고, 검색이 되니 바로 이어갈 수 있어야 했고, 그러다 보니 오래된 세션을 정리하고 싶었고, 정리하다 보니 되돌릴 수 있어야 했고, 백업을 만들다 보니 경로가 엉킨 세션을 고치고 싶어졌다. 기능을 하나씩 보태다 보니 지금의 claude-sessions v0.1.0이 됐다.

의도적으로 Python 표준 라이브러리만 사용했다. fzf도, rich도, click도 쓰지 않았다. 한 파일 sessions.py면 충분하고, Claude Code를 쓰는 환경이라면 이미 Python 3은 깔려 있을 테니 설치 장벽을 최소화하는 쪽이 맞다고 판단했다.