Claude Code 대화 기록 검색을 위한 오픈소스 TUI 도구 'ccsearch'

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

Claude Code의 세션 이력을 키워드와 의미 기반 하이브리드 검색으로 로컬에서 빠르고 안전하게 찾아주는 오픈소스 TUI 도구이다.

배경

Claude Code CLI의 기본 세션 복구 기능이 최근 20개 목록만 제공하여 과거 특정 대화를 찾기 어렵다는 문제를 해결하기 위해, 로컬 하이브리드 검색 기능을 갖춘 TUI 도구를 개발하여 공유했다.

커뮤니티 반응

Claude Code 사용자들 사이에서 세션 관리의 불편함에 공감하며 로컬 검색 방식에 대해 긍정적인 반응이 나타났다. 특히 데이터 보안을 위해 클라우드를 거치지 않는 로컬 임베딩 방식을 채택한 점이 높게 평가받았다.

실용적 조언

Claude Code 세션이 많아져 관리가 어렵다면 ccsearch를 설치하여 로컬 검색 환경을 구축할 수 있다.
정확한 단어가 기억나지 않을 때는 시맨틱 검색 기능을 활용하여 대략적인 맥락으로 과거 대화를 찾을 수 있다.
보안이 중요한 프로젝트라면 외부 API 호출 없이 로컬에서만 작동하는 임베딩 모델 기반 도구를 우선 고려한다.

섹션별 상세

Claude Code CLI의 세션 복구 기능인 --resume 플래그는 최근 20개의 세션을 단순 나열하는 방식이라 과거 대화를 찾기 어렵다. 사용자는 제목이 잘린 리스트에서 특정 버그 수정 내역이나 논의 사항을 추측하여 선택해야 하는 번거로움이 있다. 이러한 불편함은 대화 세션이 많아질수록 개발 생산성을 저해하는 요소로 작용한다.

단순 텍스트 매칭의 한계를 극복하기 위해 SQLite FTS5의 BM25 알고리즘과 로컬 임베딩 모델을 결합한 하이브리드 검색 시스템을 구축했다. 이를 통해 정확한 키워드가 생각나지 않는 상황에서도 의미적 유사성을 바탕으로 관련 세션을 찾아낼 수 있다. 검색 결과의 정교함을 높이기 위해 상호 순위 결합(Reciprocal Rank Fusion, RRF) 기법을 도입하여 두 검색 결과를 통합했다.

보안을 최우선으로 고려하여 모든 검색 데이터와 임베딩 처리는 사용자 기기 내에서만 이루어지며 외부 클라우드로 데이터가 전송되지 않는다. 80MB 수준의 경량 모델인 all-MiniLM-L6-v2를 사용하여 로컬 환경에서도 지연 시간 없는 검색 성능을 구현했다. 이는 기업 보안 정책상 외부로 대화 로그를 보낼 수 없는 환경에서도 안전하게 사용할 수 있는 구조이다.

TUI(Terminal User Interface) 기반으로 설계되어 터미널 환경을 벗어나지 않고도 빠른 검색과 세션 복구가 가능하다. 검색 결과에서 원하는 세션을 선택하고 엔터를 누르면 즉시 claude --resume 명령어가 실행되어 해당 컨텍스트로 복귀한다. 기존의 grep 방식보다 유연하며 사용자가 모호하게 기억하는 내용만으로도 과거 작업을 이어갈 수 있다.

실무 Takeaway

Claude Code 세션 이력을 키워드 및 의미 기반으로 검색할 수 있는 TUI 도구 ccsearch가 공개됐다.
SQLite FTS5(BM25)와 all-MiniLM-L6-v2 임베딩 모델을 결합한 로컬 하이브리드 검색을 지원한다.
모든 데이터 처리가 로컬에서 수행되어 보안성이 높으며 80MB의 경량 모델로 빠른 속도를 보장한다.
검색 후 즉시 세션을 재개할 수 있는 워크플로우를 통해 개발자의 컨텍스트 전환 비용을 줄였다.

언급된 도구

ccsearch추천

Claude Code 세션 검색 및 복구용 TUI 도구

all-MiniLM-L6-v2추천

로컬 시맨틱 검색을 위한 경량 임베딩 모델

SQLite FTS5추천

키워드 기반 전문 검색(Full-Text Search) 엔진