Dicklesworthstone/coding_agent_session_search

🔎 coding-agent-search (cass) – 로컬 AI 코딩 어시스턴트 기록용 통합 고성능 TUI

무엇인가요 – cass는 여러 인기 있는 코딩 에이전트(Claude Code, GitHub Copilot Chat, Cursor, Aider 등)의 대화 로그를 수집하고, 공통 JSON 스키마로 정규화하여 로컬 SQLite 아카이브에 저장한 후 즉시 검색할 수 있도록 해주는 Rust 기반 명령줄/터미널 UI 도구입니다. 완전히 오프라인으로 작동하며, 선택적 세마틱 검색은 명시적으로 설치한 작고 가벼운 MiniLM 모델을 사용해 디바이스 내에서 실행됩니다.

---

📦 설치

• 일문령 스크립트 (Linux/macOS/Windows PowerShell): 최신 릴리스를 다운로드하고 바이너리 무결성을 검증합니다.
• Homebrew tap (brew install dicklesworthstone/tap/cass) – Linux 및 Apple Silicon macOS용 사전 빌드된 tarball.
• Scoop 버킷 (Windows용).
• --version <tag>를 사용해 특정 버전으로 고정할 수 있습니다.

---

🚀 빠른 "로봇"(머신 리더블) 워크플로우

단계	명령어	기능
1	cass triage --json	아카이브의 건강 상태를 점검하고 다음 작업(next_command, recommended_commands 등)을 제안합니다.
2	cass search "…" --robot --limit 5 --fields minimal	하이브리드 검색(빠른 어휘 검색 + 선택적 MiniLM 정밀화)을 수행하고, 자동화에 적합한 JSON 결과를 반환합니다.
3	cass sessions --current --json	현재 워크스페이스와 연결된 최신 세션을 찾습니다.
4	cass view <session>.jsonl -n 42 --json	저장된 세션에서 특정 메시지(42번째 줄)를 가져옵니다.
5	cass capabilities --json	전체 머신 API 표면(triage, search, models, doctor 등)을 나열합니다.
6	cass sources agents exclude openclaw	향후 인덱싱에서 소음이 큰 에이전트를 제외합니다.

모든 로봇 명령어는 stdout에 데이터만 출력하고 진단 정보는 stderr에 출력하며, 성공 시 exit-code 0을 반환합니다.

---

✨ 주요 기능 (일반적인 언어로)

• 에이전트 간 통합 – 30개 이상의 다양한 코딩 어시스턴트 로그를 하나의 검색 가능한 타임라인으로 통합.
• 즉시 어휘 검색 – 에지-니그램 인덱싱으로 10GB 아카이브에서도 60ms 미만의 쿼리 지연을 제공.
• 선택적 세마틱 검색 – cass models install 후 MiniLM 기반 벡터 검색이 가능하며, 여전히 오프라인 상태이며, 모델이 없을 경우 순수 어휘 결과로 폴백.
• 원자적이고 크래시 안전한 인덱싱 – 각 어휘 게시는 원자적 리네임으로 수행되며, 이전 세대의 백업을 보관해 단일 스텝 롤백이 가능.
• 강력한 진단 기능 – cass doctor와 cass diag는 격리된 자산을 나열하고, 안전한 정리 작업을 제안하며, 검증된 수정을 자동 적용할 수 있습니다.
• 안정적인 JSON 계약 – 모든 로봇 모드 출력은 버전 관리된 스키마를 따르며, 골든 파일 테스트로 보호되어 하류 자동화에 안전합니다.
• 에어게이프(공기 격리) 운영 – 자체 MiniLM 파일(--from-file)을 제공해 설치 후 네트워크 접근이 필요 없음.
• 확장 가능한 "로봇" 모드 – LLM 기반 워크플로우 등 다른 에이전트에서 호출해 과거 대화를 컨텍스트로 가져올 수 있음.

---

🛠️ 내부 동작 원리 (고수준)

1. 수집 – 백그라운드 인덱서가 다양한 에이전트 전용 로그 형식을 읽어 각 메시지를 통일된 JSON 레코드로 변환하고 SQLite 데이터베이스에 기록합니다.
2. 어휘 인덱스 – Tantivy 기반의 커스텀 풀텍스트 엔진이 빠른 접두사 매칭을 위한 에지-니그램 인덱스를 구축합니다.
3. 세마틱 벡터 – MiniLM 모델이 설치되면 각 메시지가 임베딩되어 Frankensearch FSVI 벡터 파일에 저장되며, 데몬이 검색 간 재사용을 위해 제공합니다.
4. 하이브리드 쿼리 – 검색은 먼저 어휘 히트를 반환하고, 모델이 존재하면 벡터 간 코사인 유사도로 순위를 정밀화합니다.
5. 원자적 게시 – 새로운 어휘 세대는 원자적으로 스왑되며, 중단된 게시는 다음 시작 시 자동 복구됩니다.

---

👥 누가 이득을 볼 수 있나요

• 개인 개발자 – Copilot, Cursor, Claude 등을 번갈아 사용하면서도 과거 해결책을 파일을 뒤지지 않고 빠르게 회상하고 싶은 사람.
• 팀 – 모든 코딩 어시스턴트 상호작용을 공유하고, 개인정보 보호를 유지하는 지식 기반을 원하는 사람.
• AI 에이전트 파이프라인 – cass를 로봇 모드로 호출해 자신의 컨텍스트를 과거 답변으로 풍부하게 만들 수 있음.
• 파워 유저 – 안정적인 JSON API 위에 사용자 정의 분석(예: 토큰 사용량 통계)을 스크립트로 구현하고 싶은 사람.

---

📚 추가 정보

• 스크린샷 – 색상으로 구분된 에이전트, 마크다운 렌더링된 대화 보기, 내장된 도움말 화면을 갖춘 3패널 TUI.
• 설계 문서 – README에는 어휘 게시 내구성 모델, 격리/GC 정책, 정확한 오류 엔벨로프 스키마가 설명되어 있습니다.
• 모델 세부 정보 – 영어용 all-minilm-l6-v2 (90MB), CJK/혼합 텍스트용 multilingual-minilm (480MB).

---

✅ 결론

cass는 당신이 사용한 모든 AI 코딩 어시스턴트의 기록을 빠르고 오프라인으로 검색할 수 있는 통합 엔진을 제공하며, 다른 도구(또는 에이전트 자체)가 이 지식 기반에 접근할 수 있도록 견고한 CLI/JSON 인터페이스를 제공합니다. Rust로 구현되었으며 단일 바이너리로 배포되며, 모든 데이터는 당신의 기계에만 보관됩니다 — 텔레메트리도, 클라우드 호출도 없습니다.