claude-session-tracker: 쌓여만 가는 Claude Code 세션을 정리하는 cst

글쓴이 /

Claude Code를 몇 달만 쓰면 ~/.claude/projects/ 아래에 세션 jsonl 파일이 수백 개 쌓입니다. 이력을 되짚거나 방금 닫은 세션을 이어서 작업하고 싶어도, 기존 도구들은 “지금 뭐가 살아있고 뭐가 끝났는지”를 한눈에 알려주지 못합니다.

그 답답함을 해결하려고 만든 claude-session-tracker(줄여서 cst)를 소개합니다.

🧭 TL;DR

  • 모든 Claude Code 세션을 ● 세션사용중 / ○ 세션종료 / ✓ 작업종료 세 글리프로 즉시 분류한다.
  • fzf 스타일 TUI에서 / + 키워드로 실시간 필터링. 한글·일본어·중국어 입력 전부 지원한다.
  • Enter 시 TUI를 교체하지 않고 새 창을 띄워, 하나의 세션을 연 뒤에도 TUI가 살아 있어 연속으로 다른 세션을 이어받는다.
  • Python stdlib 전용. 설치는 git clone + 심볼릭 링크 한 번.

왜 필요한가 — 세션이 500개가 되는 순간

Claude Code는 대화마다 ~/.claude/projects/<cwd-slug>/<uuid>.jsonl을 append-only로 기록합니다. 한 프로젝트를 오래 쓰면 수십 개, 여러 프로젝트를 병행하면 금세 수백 개로 불어납니다.

그런데 실무에서 궁금한 건 세 가지 뿐입니다.

  1. 지금 어떤 세션이 실제로 돌고 있지? — 여러 터미널에 열어둔 Claude Code 중 어느 게 살아 있나.
  2. 어떤 건 이미 끝냈지? — 완료한 작업은 눈앞에서 치우고 싶다.
  3. 2주 전에 인증 마이그레이션하던 그 세션 어디 갔지? — 과거 컨텍스트로 복귀하고 싶다.

공식 도구는 세션 선택/재개만 가능하고, 커뮤니티 포크인 claude-sessions는 과거 세션 브라우징은 훌륭하지만 “지금 돌고 있는지”를 알려주지 않습니다. 결국 ps aux | grep claude나 터미널 탭 이름으로 추측하게 됩니다.

cst의 차별성 — 세 가지 상태로 즉시 분류

cst는 모든 세션을 단 하나의 글리프로 분류합니다. 이 글리프 하나가 위 세 질문에 동시에 답합니다. 우선순위는 ✓ > ● > ○입니다.

작업종료로 마킹한 세션은 프로세스가 살아있어도 ✓로 보여서 “신경쓸 필요 없는 세션”을 바로 구분할 수 있습니다.

Figure 1. 세 개의 데이터 소스 → 하나의 상태

Figure 1. 세 개의 데이터 소스 → 하나의 상태cst 아키텍처 다이어그램. 왼쪽에 세 개의 데이터 소스(~/.claude/projects/의 세션 트랜스크립트, ~/.claude/sessions/의 라이브 프로세스 레지스트리, ~/.cache/claude-session-tracker/의 사용자 작업종료 플래그)가 중앙의 cst 엔진으로 입력되어, 오른쪽에 세 가지 상태 글리프(● 세션사용중, ○ 세션종료, ✓ 작업종료)를 출력한다. 우선순위는 ✓ 가장 높고 그 다음 ●, 마지막 ○. ~/.claude/projects/ **/*.jsonl 세션 트랜스크립트 (source of truth) ~/.claude/sessions/ <pid>.json 라이브 프로세스 레지스트리 ~/.cache/claude-session-tracker/ state.json 사용자 작업종료 플래그 cst tracker.py resolve_status() scan_live_sessions() ● 세션사용중 PID 생존 확인됨 kill -0 <pid> → OK ○ 세션종료 프로세스 없음 또는 등록된 적 없음 ✓ 작업종료 사용자가 명시적으로 표시 state.json에 영구 저장 각 세션은 3개 데이터 소스 교차 검증 → 상태 하나로 결정 (우선순위: ✓ > ● > ○)

그림 1. 백그라운드 데몬 없이, 명령 호출 시점에 세 소스를 즉시 교차 검증해 상태를 계산한다.

어떻게 쓰나 — 가장 빠른 워크플로

셸에서 바로 리스트를 보려면 그냥 cst를 치면 됩니다.

$ cst
  #  STAT  LAST ACTIVITY     SESSION      MSGS  MESSAGE                       PROJECT
  1  ●     2026-04-22 01:17  960faaa8      261  claude-sessions 는 자체 DB...  ~/.claude/skills
  2  ✓     2026-04-22 01:15  6a33a615       25  잔여 작업 내역을 커밋해줘.    ~/project/.../csm
  3  ○     2026-04-21 21:24  afbd9e28      241  pnpm 적용 되어 있는가?        ~/project/.../url-shortener-mvp
3 session(s)  [● 세션사용중:1  ○ 세션종료:1  ✓ 작업종료:1]

진짜 생산성 향상은 TUI(cst --tui)에서 나옵니다. fzf 스타일로 타이핑하면서 동시에 이동·조작할 수 있게 설계했습니다.

Figure 2. TUI 워크플로 (4번의 키 입력으로 세션 열기)

Figure 2. TUI 워크플로 (4번의 키 입력으로 세션 열기)TUI 사용 흐름을 네 단계로 도식화. 첫 단계는 cst –tui 명령으로 전체 세션 목록 진입, 두 번째는 슬래시 키와 쿼리 입력으로 실시간 메타필터(한국어·일본어·중국어 모두 지원), 세 번째는 상하 방향키로 선택 이동 또는 Ctrl+D 로 작업종료 표시, 네 번째는 Enter 를 눌러 현재 터미널 앱과 같은 앱의 새 창을 포그라운드로 띄워 선택한 세션을 이어받기. cst –tui 전체 세션 목록 #, STAT, MESSAGE, PROJECT 컬럼 / + “쿼리” 실시간 메타필터 한글/일본어/중국어 모두 지원 ↑↓ 이동 또는 ^D mark✓ 타이핑하며 동시에 선택 이동 (fzf-style) Enter 필터 확정 → 일반 모드 Enter 한 번 더 → 새 창에서 세션 열기 TUI는 그대로 유지 → 다음 세션도 연속으로 작업 가능 현재 쓰는 터미널(iTerm/Terminal/WezTerm/Ghostty/kitty/Alacritty)과 같은 앱의 새 창, foreground로 활성화

그림 2. 네 번의 키 입력만으로 원하는 세션을 찾아서 새 창으로 연다.

💡 핵심 차별점. 기존 claude-sessions는 TUI 프로세스를 claude로 교체(execvp)해서 TUI가 사라집니다. cst는 TUI를 그대로 두고 현재 쓰는 터미널 앱과 같은 앱의 새 창을 포그라운드로 띄우기 때문에, 한 세션을 연 뒤에도 TUI로 돌아가 다음 세션을 곧바로 이어받을 수 있습니다.

기존 도구와의 비교

세 도구는 경쟁이 아니라 보완 관계입니다. claude-session-manager(csm)는 동시에 돌리고 있는 여러 터미널 창을 트리아지하는 데 최적이고, cst는 수백 개 세션 이력에서 찾아 이어받기에 최적입니다.

claude-sessionsclaude-session-managercst
역할세션 브라우저동시 실행중 세션의 작업 매니저상태 추적 포함 세션 브라우저 + 빠른 필터
라이브 상태감지 안 함감지 + 윈도우 포커스감지 (글리프 ●/○/✓)
작업종료 플래그없음있음 (메타데이터와 통합)있음 (overlay, 원본 무해)
검색 UXEnter 후 전체 스캔우선순위 기반 리스트fzf-style (타이핑하며 이동)
세션 열기execvp로 TUI 교체macOS 윈도우 포커스새 창 띄우기 (TUI 유지)
한글 검색제한적제한적지원 (수동 UTF-8 조립)
플랫폼macOS/LinuxmacOS 전용macOS/Linux
의존성stdlib여러 모듈stdlib만

구현 디테일 — 의존성 없이 풀어낸 것들

기법해결한 문제
Python stdlib 전용설치는 git clone + 심볼릭 링크 하나로 끝난다.
수동 UTF-8 바이트 조립curses.get_wch()가 WezTerm 등 일부 터미널에서 방향키 이스케이프 시퀀스를 multi-char 문자열로 반환하는 버그를 getch()로 한 바이트씩 받아 UTF-8 lead byte 패턴(0xC0/0xE0/0xF0)으로 문자 길이를 결정해 우회한다.
claude 절대 경로 주입부모 프로세스에서 shutil.which("claude")로 미리 해결해 명령에 박아넣어, 새 셸의 PATH 설정(nvm/volta/asdf)과 무관하게 실행된다.
ESCDELAY = 25ms기본 1000ms 탓에 Esc 한 번에 1초씩 대기하던 문제를 해소한다.
mtime/size 기반 인덱싱 캐시500개 세션이 있어도 두 번째 실행부터는 즉시 렌더링된다.
작업종료 overlay원본 jsonl을 건드리지 않고 별도 state.json에만 기록 — 삭제·복원이 안전하다.

설치 (30초)

요구사항: Python 3.10+, ~/.local/bin이 PATH에 포함되어 있어야 한다.

# 1. 클론
git clone https://github.com/greeun/claude-session-tracker ~/.claude/skills/claude-session-tracker
# 2. 실행 권한 + PATH 심볼릭 링크
chmod +x ~/.claude/skills/claude-session-tracker/tracker.py
mkdir -p ~/.local/bin
ln -sf ~/.claude/skills/claude-session-tracker/tracker.py ~/.local/bin/cst
# 3. 확인
cst --version
# claude-session-tracker v0.1.0

자주 쓰는 명령

명령설명
cst기본 리스트 (#, STAT, LAST, SESSION, MSGS, MESSAGE, PROJECT 컬럼).
cst --tuiTUI 진입 → / 쿼리 → ↑↓ → Enter.
cst list --status active상태별 필터 (active / ended / done).
cst search "쿼리" -i본문 풀텍스트 검색 (-i는 대소문자 무시).
cst done <id>✓ 작업종료 표시.
cst live지금 돌고 있는 Claude Code 프로세스만 표시한다.
cst backup --days 90 -y90일 이상 된 세션 아카이빙.
cst relocate <id> <new-cwd>세션에 기록된 cwd 변경.

소스 / 피드백

  • 저장소: github.com/greeun/claude-session-tracker
  • 라이선스: MIT (claude-sessions의 포크, 동일 라이선스).
  • 이슈/PR 환영합니다. 특히 Warp 스크립팅, Hyper 등 다른 터미널 앱 지원이 추가되면 좋겠습니다.
GitHub에서 보기 →

세션이 100개를 넘어가기 시작했다면, 한 번 써볼 만합니다. cst --tui를 치고 /에 키워드 한두 개를 입력해 보세요. 다시 ps aux | grep claude로 돌아가기 어려워질 겁니다.

위로 스크롤