aovestdipaperino/tokensave

tokensave – AI 코딩 에이전트를 위한 시맨틱 코드 인텔리전스

정의 – tokensave는 프로젝트 소스 코드의 시맨틱 지식 그래프를 구축하는 Rust 기반 로컬 코드 인덱싱 서버입니다. AI 기반 코딩 어시스턴트(Claude, Gemini, Cursor, Copilot 등)는 grep이나 파일 읽기 대신 이 그래프를 쿼리할 수 있어 "탐색" 작업에 소비하는 토큰 수를 획기적으로 줄일 수 있습니다.

중요성 – 대규모 언어 모델 에이전트는 토큰 단위로 과금됩니다. grep, find 등의 도구로 리포지토리를 스캔하면 에이전트가 코드 작성을 시작하기 전에 수백 개의 토큰을 소비할 수 있습니다. tokensave는 심볼, 호출 그래프, 관계를 사전 인덱싱하여 에이전트가 단일 도구 호출로 정확한 심볼, 호출자, 스니펫을 얻을 수 있게 하여 비용과 지연 시간을 절약합니다.

주요 기능

• 시맨틱 검색 – 의미(예: "authentication")로 코드를 찾고 엔트리 포인트, 관련 심볼, 소스 스니펫을 포함한 구조화된 결과를 받습니다.
• 영향 분석 – 호출자, 피호출자, 모든 심볼의 전체 변경 범위를 추적합니다.
• 멀티 브랜치 지원 – 조상 브랜치의 작업을 재사용하는 선택적 브랜치별 데이터베이스로 브랜치 전환 시 전체 재인덱싱을 강제하지 않습니다.
• 크래시 내성 동기화 – 파싱은 단기 서브프로세스에서 실행됩니다. Tree-sitter 문법의 세그폴트는 인덱싱 작업 전체가 아닌 워커만 종료합니다.
• 원자적 편집 프리미티브 – 영향을 받는 파일을 자동으로 재인덱싱하는 안전한 AST 인식 교체/삽입 작업.
• 광범위한 언어 지원 – Rust, Go, Python, TypeScript, C/C++, Swift, 셰이더 언어 등 50개 이상의 언어를 지원합니다.
• 에이전트 통합 – Claude Code, Gemini CLI, Cursor, Copilot 등 12개 이상의 에이전트를 위한 즉시 사용 가능한 MCP(메타 코딩 프로토콜) 도구 정의.

사용 방법

1. 설치 – Homebrew, Scoop, cargo binstall 또는 macOS, Linux, Windows용 사전 빌드 바이너리를 사용합니다.
2. 에이전트 등록 – tokensave install --agent <name>은 필요한 MCP 서버 항목과 훅 구성을 각 에이전트의 네이티브 구성(예: ~/.claude.json)에 작성합니다. --local 플래그를 사용하면 등록을 프로젝트별로 유지할 수 있습니다.
3. 인덱스 생성 – tokensave init는 그래프가 포함된 libSQL 데이터베이스가 있는 .tokensave/ 디렉토리를 생성합니다. 이후 변경 사항은 tokensave sync로 적용됩니다.
4. 에이전트에서 쿼리 – 에이전트는 tokensave_search, tokensave_branch_search 또는 편집 프리미티브와 같은 MCP 도구를 호출합니다. 서버는 즉시 구조화된 결과를 반환합니다.

설치 하이라이트

• 크로스 플랫폼 – macOS(Apple Silicon), Linux(x86_64/ARM64), Windows용 바이너리.
• 기능 계층 – lite, medium, full 바이너리로 바이너리 크기와 언어 지원 범위를 절충할 수 있습니다.
• 제로 트러스트 – 모든 데이터는 기기에 유지되며 API 키나 외부 서비스가 필요하지 않습니다.

고급 기능

• 멀티 브랜치 인덱싱 – tokensave branch add/list/remove 같은 명령으로 Git 훅을 통한 자동 백그라운드 추적을 사용하여 Git 브랜치별로 별도의 그래프를 유지할 수 있습니다.
• 서브프로세스 격리 추출 – 단일 잘못된 파일이 전체 동기화를 중단하지 않도록 방지합니다.
• 세션 간 메모리 – 특정 MCP 도구는 에이전트 세션 간에 컨텍스트를 유지합니다(자세한 내용은 문서 참조).

고려 대상 – LLM 기반 코딩 어시스턴트에 크게 의존하며 토큰 소비를 줄이고 응답 속도를 개선하며 코드 분석을 완전히 로컬로 유지하려는 팀.

자세한 정보 – 리포지토리의 README, docs/BRANCHING-USER-GUIDE.md 파일, crates.io의 크레이트 페이지에서 더 깊은 사용 지침과 구성 세부 정보를 제공합니다.