tokensave

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

더 적은 토큰 • 더 적은 도구 호출 • 100% 로컬

tokensave가 필요한 이유는?

AI 코딩 에이전트는 코드베이스를 탐색하면서 토큰을 낭비합니다. 모든 grep, glob, 파일 읽기는 비용이 듭니다. 복잡한 작업에서는 에이전트가 여러 Explore 하위 에이전트를 생성하여 컨텍스트를 구축하기 위해 수백 개의 파일을 스캔합니다.

tokensave는 에이전트에게 사전 인덱싱된 시맨틱 지식 그래프를 제공합니다. 파일을 스캔하는 대신 에이전트는 그래프를 쿼리하고 즉각적이고 구조화된 답변(올바른 심볼, 그 관계, 소스 코드)을 한 번의 호출로 얻습니다.

작동 방식

┌──────────────────────────────────────────────────────────────┐
│  AI Coding Agent (Claude Code, Codex, Gemini, Cursor, ...)   │
│                                                              │
│  "Implement user authentication"                             │
│        │                                                     │
│        ▼                                                     │
│  ┌─────────────────┐       ┌─────────────────┐               │
│  │  Sub-agent      │ ───── │  Sub-agent      │               │
│  └────────┬────────┘       └─────────┬───────┘               │
└───────────┼──────────────────────────┼───────────────────────┘
            │                          │
            ▼                          ▼
┌──────────────────────────────────────────────────────────────┐
│  tokensave MCP Server                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   Search    │  │   Callers   │  │   Context   │           │
│  │   "auth"    │  │  "login()"  │  │   for task  │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
│         └────────────────┼────────────────┘                  │
│                          ▼                                   │
│              ┌───────────────────────┐                       │
│              │   libSQL Graph DB     │                       │
│              │   • Instant lookups   │                       │
│              │   • FTS5 search       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

tokensave 없이: 에이전트는 grep, glob, Read를 사용하여 파일을 스캔합니다 -- 많은 API 호출, 높은 토큰 사용량.

tokensave와 함께: 에이전트는 MCP 도구를 통해 그래프를 쿼리합니다 -- 즉각적인 결과, 로컬 처리, 더 적은 토큰.

주요 기능

빠른 시작

1. 설치

Homebrew (macOS):

brew install aovestdipaperino/tap/tokensave

Scoop (Windows):

scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket
scoop install tokensave

Cargo / cargo-binstall (모든 플랫폼):

# Fast install prebuilt binary without compiling:
cargo binstall tokensave

# Or compile from source:
cargo install tokensave                          # full (50+ languages, default)
cargo install tokensave --features medium        # medium tier
cargo install tokensave --no-default-features    # lite (smallest binary)

사전 빌드된 바이너리 (Linux, Windows, macOS):

최신 릴리스에서 다운로드하고 바이너리를 PATH에 배치합니다.

2. 에이전트 구성

tokensave install                         # auto-detects installed agents
tokensave install --agent antigravity     # Google Antigravity (formerly Windsurf)
tokensave install --agent auggie          # AugmentCode
tokensave install --agent claude          # Claude Code
tokensave install --agent cline           # Cline
tokensave install --agent codex           # OpenAI Codex CLI
tokensave install --agent copilot         # GitHub Copilot
tokensave install --agent cursor          # Cursor
tokensave install --agent droid           # Factory Droid
tokensave install --agent gemini          # Gemini CLI
tokensave install --agent kilo            # Kilo CLI
tokensave install --agent kiro            # AWS Kiro
tokensave install --agent kimi            # Moonshot Kimi CLI
tokensave install --agent omp             # Oh My Pi (OMP)
tokensave install --agent opencode        # OpenCode
tokensave install --agent pi              # Pi (pi.dev)
tokensave install --agent plank           # Plank (macOS only)
tokensave install --agent qwen            # Qwen Code
tokensave install --agent roo-code        # Roo Code
tokensave install --agent vibe            # Mistral Vibe
tokensave install --agent zed             # Zed
tokensave install --agent grok            # Grok Build (xAI)
tokensave install --git-hook yes           # auto-install the global post-commit and post-checkout hooks (no prompt)
tokensave install --git-hook no            # skip the post-commit and post-checkout hooks (no prompt)
tokensave githooks                         # show which global git hooks tokensave owns
tokensave githooks off                     # remove them, leaving any hook content you wrote

각 에이전트는 네이티브 구성 형식으로 MCP 서버가 등록됩니다. Claude Code는 추가로 PreToolUse 훅(낭비적인 Explore 에이전트 차단), UserPromptSubmit 훅, Stop 훅, CLAUDE.md의 프롬프트 규칙, 자동 허용 도구 권한을 얻습니다. Kiro는 전역 MCP 구성, 리소스로 로드된 tokensave.md 스티어링, 허용적인 내장/tokensave 도구 승인, 위임 가드레일 훅, 쓰기 후 동기화가 있는 tokensave 관리 기본 에이전트를 얻습니다; 사용자 관리 Kiro 에이전트는 보존됩니다.

전역 OMP 설치는 bare omp config path이 보고한 프로필을 대상으로 하여 <resolved-agent-dir>/mcp.json 및 <resolved-agent-dir>/rules/tokensave.md을 작성합니다. 명명된 프로필에 설치할 때 OMP_PROFILE 또는 OMP의 호환 PI_PROFILE을 내보냅니다; OMP의 리졸버는 PI_CONFIG_DIR 및 PI_CODING_AGENT_DIR도 존중합니다. Tokensave는 OMP의 프로필 로직을 복제하는 대신 해당 네이티브 리졸버를 신뢰합니다. Tokensave는 OMP용 MCP 및 권고 규칙을 설치합니다; OMP 훅 강제는 설치하지 않습니다.

모든 변경은 멱등적입니다 -- 업그레이드 후 다시 실행해도 안전합니다. 에이전트 설정 후 전역 git post-commit 및 post-checkout 훅이 제공됩니다. tokensave uninstall은 에이전트 통합과 함께 해당 훅을 제거합니다; --keep-git-hooks를 전달하여 남겨두거나 tokensave githooks로 별도 관리합니다.

프로젝트 로컬 설치

기본적으로 tokensave install은 전역 에이전트 구성(예: ~/.claude.json)에 MCP 서버를 등록합니다. 현재 프로젝트에만 tokensave를 등록하려면 --local을 추가합니다:

tokensave install --local --agent claude
tokensave install --local --agent omp

이것은 커밋하고 팀과 공유할 수 있는 프로젝트 범위 구성을 작성합니다. Claude의 경우 ./.mcp.json, ./.claude/settings.json, ./CLAUDE.md입니다; OMP는 OMP CLI를 호출하지 않고 ./.omp/mcp.json 및 ./.omp/rules/tokensave.md을 사용합니다. 지원되는 에이전트: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank (각각 자체 프로젝트 파일을 작성합니다, 예: plank의 경우 .cursor/mcp.json, .factory/mcp.json, .gemini/settings.json, .zed/settings.json, opencode.json, .roo/mcp.json, .kiro/settings/mcp.json, .augment/settings.json, .omp/mcp.json, .mcp.json). 다른 에이전트는 프로젝트 범위 구성을 가지지 않으며 --local로 오류를 보고합니다.

프로젝트 로컬 설치는 tokensave uninstall --local로 제거합니다.

3. 프로젝트 인덱싱

cd /path/to/your/project
tokensave init

이것은 지식 그래프 데이터베이스가 있는 .tokensave/ 디렉토리를 생성합니다. 초기화와 동기화는 별도의 명령입니다: init은 프로젝트당 일회성 옵트인이고, sync은 이미 초기화된 프로젝트만 업데이트합니다. 이렇게 하면 전역 git 훅이 인덱싱하려는 의도가 없는 저장소에 데이터베이스를 조용히 생성하는 것을 방지합니다. init 후에는 tokensave sync을 사용하여 증분 업데이트합니다 -- 변경된 파일만 재인덱싱됩니다.

{
  "mcpServers": {
    "tokensave": {
      "command": "/path/to/tokensave",
      "args": ["serve"]
    }
  }
}

크래시 내성 동기화

트리-시터 문법은 컴파일된 C/C++ 코드입니다. 때때로 내부 어서션에 도달하거나 Rust 패닉 처리로 가로챌 수 없는 경로로 프로세스를 종료합니다. v4.3.0부터 모든 파일은 수명이 짧은 작업자 하위 프로세스 내에서 파싱됩니다: 문법이 segfault, abort() 호출, 스택 오버플로우가 발생하면 작업자만 죽습니다. 풀이 재생성하고 문제 파일은 기록되고 건너뛰며 sync은 계속 진행됩니다.

작업자는 숨겨진 extract-worker 하위 명령으로, 256비트 스폰당 토큰으로 부모에 대해 인증되며 TOKENSAVE_WORKER_TOKEN 환경 변수와 stdin에서 받은 첫 32바이트로 모두 필요합니다. 사용자의 직접 호출은 실패합니다. 기본값은 available_parallelism() 작업자입니다; TOKENSAVE_DISABLE_SUBPROCESS=1으로 옵트아웃합니다.

편집 프리미티브(tokensave_str_replace, tokensave_insert_at 등)는 여전히 프로세스 내에서 실행됩니다: 하위 프로세스 오버헤드가 지배할 한 번에 하나의 파일을 대상으로 하며, 추출기 크래시는 에이전트에게 즉시 표시됩니다.

멀티 브랜치 인덱싱 (선택)

tokensave는 선택적으로 git 브랜치별로 별도의 코드 그래프를 유지할 수 있습니다. 활성화하면 브랜치 전환 시 오래된 결과를 얻지 않으며 다른 브랜치에서 이미 파싱한 파일을 재인덱싱하지 않습니다. 멀티 브랜치 추적은 옵트인입니다 -- 없으면 tokensave는 모든 브랜치에 단일 데이터베이스를 사용합니다.

작동 방식

브랜치를 추적할 때 tokensave는 가장 가까운 조상 DB를 복사하고 다른 파일만 동기화합니다. 즉, main에서 기능 브랜치를 추적하는 것은 거의 즉각적입니다 -- 변경한 파일만 파싱합니다.

CLI 명령

tokensave branch add              # track the current branch
tokensave branch list             # see tracked branches and DB sizes
tokensave branch remove <name>    # stop tracking a branch
tokensave branch removeall        # remove all tracked branches except default
tokensave branch gc               # clean up branches deleted from git

브랜치 간 MCP 도구

세 가지 MCP 도구로 체크아웃을 전환하지 않고 브랜치 간 쿼리가 가능합니다:

• tokensave_branch_search -- 다른 브랜치의 그래프에서 심볼 검색
• tokensave_branch_diff -- 두 브랜치 간 코드 그래프 비교: 추가, 제거, 변경된(시그니처 다름) 심볼. 파일 및 종류 필터 지원.
• tokensave_branch_list -- DB 크기, 부모 브랜치, 동기화 시간이 있는 추적된 브랜치 목록

브랜치 폴백

MCP 서버가 현재 브랜치의 데이터베이스를 찾을 수 없으면 가장 가까운 조상 브랜치의 DB에서 제공하고 tokensave branch add을 실행하라는 경고를 모든 도구 응답에 포함합니다.

자동 브랜치 추적 (v7.3.0)

멀티 브랜치 모드가 부트스트랩되면(첫 수동 tokensave branch add이 브랜치 메타데이터를 생성), 새 브랜치는 조상 DB로 폴백하는 대신 자동으로 추적할 수 있습니다. 두 가지 독립 메커니즘이 이를 다룹니다; 단일 DB 모드의 프로젝트는 영향을 받지 않으며 어느 메커니즘도 기본 브랜치의 데이터베이스를 건드리지 않습니다. Git 훅(브랜치 체크아웃 시). post-checkout 훅은 tokensave install가 설정하며, 브랜치 체크아웃(파일 체크아웃과 반대)을 인식하고 백그라운드에서 tokensave branch add를 실행합니다. 해당 명령은 브랜치가 이미 추적 중이거나 기본 브랜치인 경우 아무 작업도 하지 않으므로, 알려진 브랜치 간의 일반적인 전환에는 비용이 들지 않습니다. 새로운 git clone 및 새 git worktree add의 최초 체크아웃도 브랜치 체크아웃이며, 기본 브랜치가 아닌 브랜치에 도달할 수 있습니다(git clone -b feature, git worktree add -b feature). 이 경우 훅은 먼저 tokensave init를 실행하고 그다음에 tokensave branch add를 순서대로 실행합니다. 이전 버전이 작성한 훅은 설치 당시의 본문을 유지합니다(설치 프로그램은 기존 훅을 다시 쓰지 않음). 따라서 해당 설치에서는 새 작업 트리에 여전히 아래의 auto_track 또는 수동 tokensave branch add가 필요합니다.

열기 시 자동 추적(옵트인). TokenSave::open가 실행될 때(CLI 명령 또는 MCP 서버 시작) 활성 브랜치가 추적되지 않으면, tokensave는 가장 가까운 추적된 조상의 DB를 복사하고 브랜치 메타데이터에 기록하여 즉시 추적할 수 있습니다. 이 기능은 auto_track 구성 필드(기본값 false) 또는 TOKENSAVE_AUTO_TRACK 환경 변수에 의해 제어되며, 환경 변수는 실행별로 구성을 재정의합니다(값이 0, false, no, off 또는 비어 있지 않으면 활성화). 복사는 수동 branch add가 수행하는 것과 동일한 거의 즉각적인 조상 DB 복사입니다. 그 시점에는 동기화가 실행되지 않습니다. post-commit 훅이 커밋 시 새 브랜치 DB를 최신 상태로 유지하거나, tokensave sync를 실행하여 즉시 새로 고칩니다. 자동 추적은 엄격히 최선의 노력 방식입니다. 실패는 경고로 보고되고 open()는 일반적인 조상 폴백으로 진행되므로 도구 호출을 중단할 수 없습니다.

요약하자면, 훅이 설치된 상태에서 새 기능 브랜치(새 클론 또는 작업 트리가 시작되는 브랜치 포함)를 체크아웃하면 투명하게 자체 브랜치별 그래프가 제공됩니다. auto_track가 활성화된 경우, 체크아웃 외부에서 생성된 브랜치도 tokensave가 해당 브랜치에서 프로젝트를 처음 열 때 포착됩니다.

전체 가이드는 docs/BRANCHING-USER-GUIDE.md를 참조하세요.

세션 간 메모리

세 가지 MCP 도구가 결정 사항과 코드 영역 컨텍스트를 세션 간에 유지하며, 프로젝트별 .tokensave/tokensave.db에 저장됩니다.

이를 사용하여 에이전트가 세션 간에 아키텍처 선택을 다시 설명하지 않도록 하세요.

절약 원장

모든 MCP 호출은 ~/.tokensave/global.db(savings_ledger 테이블)에 추가 전용 행을 기록합니다. tokensave gain로 검사하세요:

tokensave gain                    # current project, last 30 days
tokensave gain --all              # all projects
tokensave gain --history --range 7d
tokensave gain --json

달러 추정치는 기존 가격 책정 모듈(Sonnet 입력 가격, LiteLLM을 통해 매일 새로 고침)을 사용합니다.

재현 가능한 벤치마크

tokensave bench는 고정 쿼리 세트를 tokensave_context를 통해 실행하고 전체 파일 기준선 대비 검색 절약을 보고합니다(CCE 방법론을 반영):

tokensave bench                                    # ships with 10 default queries
tokensave bench --queries my-queries.toml --json
tokensave bench --max-nodes 5

이 저장소(tokensave 자체)에 대해 제공된 일반 쿼리 세트로 측정:

종합: 평균 88% 검색 절약(10개 쿼리에서 142.8k → 5.5k 토큰).

기본 쿼리 세트는 대부분의 애플리케이션 코드베이스(CLI, 데몬, 서비스)에 존재하는 패턴을 대상으로 합니다. tokensave bench로 자신의 프로젝트에서 실행하여 숫자를 확인하거나, 더 정밀한 검색을 위해 맞춤 쿼리 파일(--queries my.toml)을 작성하세요.

대규모 실제 저장소에 대한 Criterion 벤치

benches/large_repos.rs는 criterion 마이크로 벤치마크로, 고정된 refs에 고정된 네 개의 대규모 오픈 소스 코드베이스에 대해 MCP 도구를 종단 간 실행합니다. 각 도구는 저장소당 한 번 인덱싱된 그래프에서 샘플링된 인수(노드 ID, 정규화된 이름, 파일 글로브 등)가 있는 최소 5개 쿼리로 구동되므로 실행 간에 타이밍이 재현 가능합니다.

저장소 및 고정 refs(benches/repos.rs에 정의):

각 저장소는 첫 사용 시 얕은 클론(git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD)으로 로컬에 캐시되며, 이후 실행은 체크아웃을 재사용합니다. Git 출력은 터미널로 스트리밍되어 멀티 GB 페치가 실시간 진행 상황을 보여줍니다.

다루는 도구(각 5개 쿼리). 읽기 도구 — search, context, callers, callees, node, by_qualified_name, signature, impact, body, files, complexity, doc_coverage, largest, hotspots, god_class, module_api, derives, dead_code, rank, coupling, circular. 쓰기 도구 — str_replace, multi_str_replace, insert_at, 및 (ast-grep가 PATH에 있는 경우) ast_grep_rewrite.

모든 실행에서 강제 동기화. 벤치마크가 시작되기 전에 하네스는 각 저장소에서 tokensave sync --force에 해당하는 작업을 실행하므로(.tokensave/ 신선도와 관계없이 index_all()) 타이밍은 항상 고정된 소스를 반영합니다.

쓰기 벤치 및 정리. 쓰기 도구는 파일을 변경합니다. "일치 항목이 고유해야 함" 전제 조건을 유지하기 위해 하네스는 criterion의 iter_batched를 사용합니다. <repo>/.tokensave-bench-scratch/ 아래의 작은 스크래치 파일이 모든 타이밍 반복 전에 알려진 내용으로 다시 작성된 다음 편집 도구가 해당 파일에 대해 실행됩니다. 모든 벤치마크가 끝난 후 하네스는 각 준비된 저장소 내에서 git stash --include-untracked && git stash drop를 실행하여 작업 트리가 고정된 ref로 돌아가도록 합니다.

Criterion 구성. 벤치는 criterion의 기본값을 sample_size = 10 및 measurement_time = 30s로 재정의합니다(기본 100 / 5초 대신). 이는 각 쿼리 타이밍에 약 30초의 측정 시간을 제공하며, polkadot-sdk의 tokensave_context와 같은 느린 도구도 안정적인 숫자를 생성하기에 충분합니다.

실행:

# Required: a writable cache directory for the cloned repos + their indexes.

<p align="center">
  <a href="https://ai.enzolombardi.net/"><img src="https://img.shields.io/badge/built%20with-AI-D97757?style=flat-square&labelColor=101010&logo=anthropic&logoColor=white" alt="Built with AI — part of Enzo Lombardi's AI portfolio"></a>
</p>

# Expect several GB of disk and a long first run (shallow clone + full index of each repo).
export TOKENSAVE_BENCH_REPOS_DIR=~/tokensave-bench-cache

cargo bench --bench large_repos

TOKENSAVE_BENCH_REPOS_DIR가 설정되지 않으면 벤치는 공지사항을 출력하고 0개의 벤치마크를 등록하므로(기여자 머신에서 cargo bench --all가 저렴하게 유지됨).

구성(모두 선택 사항, 환경 변수 사용):

벤치마크 필터링은 표준 criterion CLI를 사용합니다. 예를 들어, scipy에서 search 도구만:

cargo bench --bench large_repos -- 'scipy/tokensave_search'

보고서(HTML + 원시 샘플)는 target/criterion/ 아래에 생성됩니다.

고정된 refs를 변경하려면(예: 최신 릴리스 또는 특정 SHA로) benches/repos.rs에서 REPOS를 편집하고 해당 $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref 마커를 삭제하여 다음 실행에서 다시 페치하도록 하세요. 사후 정리를 건너뛴 경우(예: 벤치 중간에 Ctrl-C), 각 저장소 디렉터리 내에서 git stash --include-untracked && git stash drop를 실행하여 수동으로 복원하세요.

MCP 테스트 매트릭스 프로브(scripts/mcp_probe)

scripts/mcp_probe/는 구성 가능한 실제 저장소 세트에 대해 stdio를 통해 tokensave serve를 구동하고 언어당 5개 쿼리 변형으로 모든 읽기 전용 MCP 도구를 실행하여 도구별/저장소별 상태 테이블을 생성하는 Python 하네스입니다. 동일한 하네스는 두 가지 목적을 제공합니다:

• 회귀 스윕. 새 언어 지원, 새 도구 또는 리팩터링 — 매트릭스를 다시 실행하고 새로 오류, 시간 초과 또는 빈 결과를 반환하는 셀은 🚩로 표시됩니다.
• 성능 프로브. 호출별 타이밍이 TSV로 기록됩니다. 동일한 고정 코퍼스는 대략적인 교차 버전 비교로도 사용됩니다. 현재 tokensave_inheritance_depth 주기 버그는 polkadot-sdk의 단일 도구가 >60초에 시간 초과되었을 때 이 하네스로 발견되었습니다.

구성 — probe.py는 드라이버입니다(ID 일치 JSON-RPC로 느린 도구가 후속 호출을 오염시키지 않음), isolated.py는 호출당 새 서버로 단일 도구를 다시 실행합니다(서버 대기열 회피), build_matrix.py는 TSV를 읽고 마크다운을 생성합니다, tools/<lang>.py 모듈은 언어별 쿼리 세트를 제공합니다(Rust 포함, 새 모듈을 추가하여 Python/Go/… 추가 가능), repos.toml는 대상 저장소를 나열합니다($TOKENSAVE_PROBE_REPOS로 재정의 가능).

빠른 실행:

cargo build --release --bin tokensave
python3 scripts/mcp_probe/probe.py
python3 scripts/mcp_probe/build_matrix.py > matrix.md

출력 셀은 ✓ 5/5(정상), 🐛 e/N(오류), ⏱ N/N(시간 초과), ∅ E/N(빈 결과), 🐢 ok/slow(>10초 호출)입니다. 오류 또는 시간 초과가 있는 셀은 가장 오른쪽 열에 🚩가 표시됩니다. 각 오류의 처음 100자와 함께 호출별 세부 정보는 후속 조치를 위해 TSV 로그에 기록됩니다.

위의 criterion 벤치와 다릅니다: criterion은 고정된 refs의 집중된 도구 세트에 대한 반복당 대기 시간을 측정하고 target/criterion/ 아래에 통계 보고서를 생성합니다. mcp_probe는 가리키는 모든 저장소에서 더 넓은 쿼리 세트로 모든 도구를 실행하며, 측정 정밀도보다 적용 범위의 폭을 최적화합니다.

80개 이상의 MCP 도구

서버는 80개 이상의 도구를 노출합니다(선택적 ast-grep 바이너리가 PATH에 없으면 하나 적음). 아래 표는 가장 일반적으로 사용되는 도구를 범주별로 그룹화합니다. 대부분은 읽기 전용이며, 병렬로 안전하게 호출할 수 있고 readOnlyHint로 주석 처리됩니다. 편집 기본 요소는 단일 파일로 범위가 지정되고 제자리에서 다시 인덱싱됩니다. 세션 기준선 및 메모리 기록 도구도 로컬 .tokensave 상태를 변경하며 비읽기 전용으로 주석 처리됩니다. 세 가지 핵심 도구(tokensave_context, tokensave_search, tokensave_status)는 anthropic/alwaysLoad로 표시되어 클라이언트의 도구 검색 왕복을 우회합니다.

다른 초기화된 프로젝트 쿼리

의미론적 읽기 도구는 MCP 서버를 다시 시작하지 않고 명시적으로 선택된 로컬 그래프를 쿼리할 수 있습니다:

{
  "query": "screenGate",
  "graph_root": "/absolute/path/to/typewhisper"
}

선택된 결과에는 정식 루트/브랜치 출처가 포함됩니다. 노드 ID는 해당 그래프에 네임스페이스가 지정되며, 일치 선택자는 후속 호출에서 반복되어야 합니다. 예를 들어, 브랜치 선택 쿼리의 후속 호출에는 두 값이 모두 포함됩니다:

{
  "node_id": "graph:<fingerprint>:function:<raw-id>",
  "graph_root": "/absolute/path/to/typewhisper",
  "graph_branch": "feature/auth"
}

graph_root는 이미 초기화된 프로젝트의 정확한 절대 루트여야 합니다. graph_branch는 선택 사항이며, 제공된 경우 추적된 브랜치를 지정해야 합니다. 선택된 열기는 읽기 전용입니다: 초기화, 동기화, 마이그레이션, 자동 추적 또는 그래프/소스 데이터 쓰기를 절대 수행하지 않습니다. 또한 절약 회계에 기여하지 않습니다. 선택자 없이 호출하면 이전과 정확히 동일하게 동작합니다. graph_root는 다른 프로젝트가 존재한다는 것을 알고 있을 때만 유용하므로, 서버는 이를 알려줍니다: 서빙되는 루트 바로 옆에 있는 초기화된 프로젝트들은 MCP instructions, tokensave_status, 그리고 빈 tokensave_search / tokensave_context 결과에 이름이 표시됩니다 — 세션이 기호가 존재하지 않는다고 결론을 내리고 옆을 살펴보지 않게 되는 지점입니다 (#375). 직계 형제 프로젝트만 최대 5개까지 제공되며, 그들을 위해 아무것도 열리거나 인덱싱되지 않습니다; 하나를 쿼리하려면 여전히 명시적인 graph_root가 필요합니다.

선택자는 쓰기, 셸 실행, 또는 현재 체크아웃에 의존하는 도구에는 의도적으로 사용할 수 없습니다: 편집 프리미티브, VCS 및 브랜치 도구, 진단 및 테스트 실행, 의존성 및 런타임 인트로스펙션, 워크플로 및 세션 메모리 도구, 영구 캐시 도구 (tokensave_redundancy), 그리고 서버 관리. 해당 도구들은 선택자를 조용히 무시하는 대신 거부합니다.

검색

비코드 아티팩트

tokensave_files는 소스 이상을 다룹니다. 확장자가 artifact_extensions에 나열된 파일 (기본적으로 .feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md)은 경로로 추적되어 "로그인 흐름의 .feature 파일이 어디 있지?" 같은 질문에 차단된 find 대신 그래프 답변이 있습니다 (#323). 이들은 절대 파싱되지 않으며 기호를 기여하지 않습니다; kind: "artifact"와 kind: "code"는 둘 사이를 필터링하며, "코드"를 의미하는 분석은 이들을 제외합니다. 언어 추출기가 이미 처리하는 확장자는 이 목록에서 무시되므로, 언어가 파싱되는 것을 막는 데 사용될 수 없습니다.

이 목록은 또한 리터럴 검색이 내부를 볼 수 있는 것을 결정합니다 (#442). literal: true에 대한 리터럴(tokensave_search) 검색은 기호 대신 바이트를 읽으므로 파서가 필요 없습니다 — 그러나 인덱싱된 파일을 반복하므로 인덱스가 행을 보유한 파일에만 도달할 수 있습니다. 추적된 .html 템플릿 또는 .css 스타일시트는 추출기도 기본 아티팩트 항목도 없으므로 해당 일치 항목이 누락됩니다; 여기에 확장자를 추가하고 tokensave sync -f를 실행하면 해당 줄이 다른 줄처럼 검색되며, 기호 컨텍스트가 없으므로 enclosing: null로 보고됩니다. 추적된 모든 파일에 도달할 수 없었던 리터럴 응답은 개수와 확장자를 명명하는 unscanned 블록에서 이를 명시하므로, 부분 답변이 완전한 답변으로 제시되지 않습니다.

호출 그래프 및 영향

코드 품질

코드 건강 분석

다섯 개의 도구가 기존 그래프에서 구조적 품질 신호를 표면화합니다. 복합 점수는 독립적인 차원에 대한 기하 평균을 사용하므로 단일 차원이 게임될 수 없습니다.

세션

AI 코딩 세션 시작 시 건강 메트릭을 스냅샷하고, 끝에서 diff하여 무엇이 개선되거나 퇴보했는지 확인합니다.

편집 프리미티브

에이전트가 정규식이나 셸 인용 위험 없이 파일을 수정할 수 있게 하는 네 개의 작성자 도구. 각각 단일 파일, 앵커 기반이며, 쓰기 후 제자리 재인덱싱을 트리거하여 그래프가 절대 오래되지 않도록 합니다.

Git 및 워크플로

타입 시스템

포팅

다중 브랜치

MCP 리소스

네 개의 리소스가 resources/list 및 resources/read를 통해 노출됩니다:

• tokensave://status -- JSON 형식의 그래프 통계
• tokensave://files -- 디렉토리별로 그룹화된 인덱싱된 파일 트리
• tokensave://overview -- 언어 분포 및 기호 종류가 있는 프로젝트 요약
• tokensave://branches -- DB 크기 및 부모 정보가 있는 추적된 브랜치

토큰 추적

tokensave는 모든 MCP 도구 호출에서 저장하는 토큰을 측정합니다. 각 도구 응답에는 해당 특정 호출로 피한 원시 파일 토큰 수를 보여주는 tokensave_metrics: before=N after=M 줄이 포함됩니다.

보고 끄기. 메트릭 줄은 MCP instructions의 문장과 함께 에이전트에게 절약분을 보고하도록 요청합니다 — 이는 모델이 tokensave가 입력 토큰에서 만든 절약을 설명하는 데 출력 토큰을 소비한다는 것을 의미합니다. 출력 토큰은 더 비싼 종류이므로, 에이전트가 거의 모든 턴에서 tokensave를 언급하면 그 설명이 이득을 상쇄할 수 있습니다 (#356). .tokensave/config.json에서 report_savings를 false로 설정하거나, TOKENSAVE_REPORT_SAVINGS 환경 변수를 실행별로 재정의하도록 설정하십시오 (0, false, no, off, 또는 빈 값을 제외한 모든 값이 활성화). 메트릭 줄과 지침이 모두 사라집니다; tokensave install도 에이전트 프롬프트 파일에 보고 규칙을 쓰는 것을 중지합니다. 측정은 어느 쪽이든 변경되지 않습니다 — 모든 호출은 여전히 절약 원장에 기록되므로 tokensave gain, tokensave list, status 및 monitor는 이전과 정확히 동일하게 보고합니다. 기본값은 true로 유지됩니다.

비용 관찰 가능성

tokensave cost                     # 7-day cost summary (default)
tokensave cost today               # today only
tokensave cost --by-model          # breakdown by Claude model
tokensave cost --by-task           # breakdown by task category (coding, debugging, exploration, ...)
tokensave cost --export json       # JSON export to stdout
tokensave cost --export csv        # CSV export to stdout

Claude Code 세션 트랜스크립트 (~/.claude/projects/**/*.jsonl)를 파싱하고, 각 API 턴을 13개의 작업 범주 중 하나로 분류하며, 모델 가격을 사용하여 달러 비용을 계산하고, 빠른 집계 쿼리를 위해 ~/.tokensave/global.db에 결과를 저장합니다. 가격은 LiteLLM에서 24시간마다 새로 고쳐지며, 오프라인일 때 내장 테이블로 대체됩니다.

tokensave status 헤더에는 오늘의 지출, 7일 총계, 효율 비율 (저장된 토큰 / 총 토큰)을 보여주는 비용 행이 포함됩니다. tokensave monitor TUI는 절약 피드 옆에 실시간 비용 패널을 표시합니다. 각 Claude Code 세션 끝에서 hook_stop 핸들러는 터미널에 한 줄 영수증을 출력합니다.

작업 분류 범주: 코딩, 디버깅, 기능 개발, 리팩토링, 테스트, 탐색, 계획, 위임, Git 작업, 빌드/배포, 브레인스토밍, 대화, 일반. 분류는 결정적입니다 (도구 이름 및 Bash 명령의 패턴 매칭), LLM 호출이 필요 없으며, AgentSeal/codeburn에서 각색되었습니다.

라이브 모니터

tokensave monitor

~/.tokensave/monitor.mmap의 공유 메모리 매핑 링 버퍼를 통해 모든 프로젝트의 MCP 도구 호출을 실시간으로 보여주는 전역 TUI. 각 항목은 프로젝트 이름, 도구 이름, 토큰 델타를 표시합니다. 상단의 비용 패널은 오늘의 지출, 절약, 효율, 최고 모델을 보여줍니다 (30초마다 새로 고침).

메모리 진단

tokensave memory [--clean]

기계 전체 메모리 보고서는 모든 tokensave 프로세스(MCP 서버, 동기화, 인덱스 실행)에 대해 ~/.tokensave/memory.mmap의 공유 메모리 매핑 테이블을 통해 제공됩니다. 각 인스턴스는 시작 시, MCP 도구 호출 시, 그리고 동기화/해석 단계 전후에 자체 RSS를 최선의 노력으로 샘플링하므로, 보고서에는 현재 및 최대 RSS가 최대값을 생성한 단계와 함께 표시됩니다 — 이는 높은 메모리 사용량을 추적하는 데 필요한 데이터입니다(#253 참조). 행은 alive, dead(OOM으로 종료된 프로세스는 최대값/단계를 포렌식 기록으로 남깁니다), 또는 orphan(아직 실행 중이지만 init으로 재부모화됨)로 표시됩니다. --clean는 죽은 슬롯을 정리합니다.

PEAK PHASE은 가장 높은 샘플의 이름을 지정하므로 샘플링만큼만 정확합니다. 증분 동기화는 순서대로 기록합니다: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. 전체 인덱스는 index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done를 기록합니다.

각 항목은 이름이 지정된 작업 후에 기록됩니다. 이전에는 작업 전에 기록되어 모든 샘플이 다음 단계의 레이블로 이전 단계의 RSS를 보고했습니다 — 이로 인해 73MiB가 실제로는 해결되지 않은 참조 로딩에 속하는 노드 로드에 귀속되었고, 해당 단계에는 샘플이 전혀 없었으며, 메모리 조사가 수개월 동안 잘못된 하위 시스템을 가리키게 되었습니다(#409). 단계를 추가하는 경우 작업 후에 샘플링하고, 최대값을 보유할 만큼 큰 단계에는 샘플을 추가하세요.

세션 및 수명 카운터

tokensave current-counter          # show per-project session counter
tokensave reset-counter            # reset the session counter
tokensave status                   # shows project + global lifetime totals + cost

tokensave status은 프로젝트 인덱스 통계, 언어 분류, 비용 행(오늘 / 7일 / 효율성), 프로젝트 및 전 세계 수명 합계를 렌더링합니다:

전 세계 카운터

모든 tokensave 사용자는 익명 집계 카운터에 기여합니다. tokensave status은 프로젝트 합계와 전 세계 합계를 모두 표시합니다. 업로드는 식별 정보 없이 단일 숫자(예: 4823)만 보냅니다. tokensave disable-upload-counter으로 옵트아웃할 수 있습니다.

인덱스 신선도

tokensave는 백그라운드 데몬이나 OS 수준 파일 감시자 없이 그래프를 최신 상태로 유지합니다.

요청 시 오래된 파일 검사. 모든 MCP 도구 호출은 마지막 동기화 이후 인덱스된 파일이 수정되었는지 확인합니다. 오래된 파일이 발견되면 도구 응답이 반환되기 전에 다시 추출됩니다. 30초 쿨다운은 연속 호출이 매 키 입력마다 트리를 다시 탐색하는 것을 방지합니다.

연결 시 따라잡기 동기화. MCP 서버가 시작되면 에이전트가 연결되지 않은 동안 발생한 변경 사항(예: git pull, IDE 편집, 빌드 단계)을 즉시 포착하는 비차단 따라잡기 동기화를 실행하므로 세션의 첫 번째 도구 호출은 신선한 인덱스를 볼 수 있습니다.

다중 에이전트 작업 및 git 작업 트리. 여러 에이전트가 동일한 프로젝트에서 동시에 작업할 때, 각 에이전트가 자체 git 작업 트리에서 작업한다는 강력한 가정이 있습니다. 작업 트리는 동일한 저장소의 독립적인 파일 시스템 체크아웃입니다: 에이전트 A와 에이전트 B는 각각 모든 파일의 자체 사본을 가지므로 서로의 진행 중인 편집을 덮어쓰지 않습니다. tokensave는 메인 체크아웃 내부에 중첩된 작업 트리에서 쿼리가 오는 것을 자동으로 감지하고 올바른 브랜치 그래프에서 결과를 제공합니다. 변경 사항은 독립적으로 누적되며 결국 git merge 또는 rebase를 통해 조정됩니다 — 다른 병렬 개발과 동일한 프로세스입니다. 이 설계는 공유 변경 가능 디렉토리에 대한 교차 에이전트 잠금의 복잡성과 실패 모드를 피합니다.

CLI 전용 워크플로. 에이전트가 연결되지 않은 상태( MCP 서버 없음)에서 tokensave 명령을 실행하면 명령 사이에 오래된 파일 검사가 실행되지 않습니다. git 훅을 설치하여 커밋이나 클론 후 인덱스를 자동으로 최신 상태로 유지하세요:

cp scripts/post-commit scripts/post-checkout .git/hooks/
chmod +x .git/hooks/post-commit .git/hooks/post-checkout

5.x에서 업그레이드

독립형 tokensave daemon 명령과 launchd/systemd/Windows 서비스 자동 시작은 6.0.0에서 제거되었습니다. 데몬을 대체한 임베디드 OS 수준 파일 감시자는 6.1.1에서 자체적으로 제거되었습니다(깊은 node_modules 또는 target 트리가 있는 대규모 모노레포에서 CPU 및 메모리 폭주를 유발했습니다). 위의 요청 시 오래된 파일 모델이 현재 설계입니다.

여전히 5.x의 데몬 자동 시작이 있다면 제거하세요:

• macOS: launchctl unload ~/Library/LaunchAgents/com.tokensave.daemon.plist && rm ~/Library/LaunchAgents/com.tokensave.daemon.plist
• Linux: systemctl --user disable --now tokensave-daemon && rm ~/.config/systemd/user/tokensave-daemon.service
• Windows: sc.exe delete tokensave-daemon (관리자 터미널에서)

정확한 이름이 기억나지 않으면: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

자체 업그레이드

tokensave upgrade                  # upgrade to latest in current channel
tokensave channel                  # show current channel (stable/beta)
tokensave channel beta             # switch to beta channel
tokensave channel stable           # switch back to stable

tokensave upgrade은 GitHub 릴리스에서 올바른 플랫폼 바이너리를 다운로드하고 실행 중인 바이너리를 제자리에서 교체합니다. 안정 및 베타 채널을 독립적으로 지원합니다.

버전 관리 및 업그레이드

tokensave 버전 번호는 SemVer처럼 보이지만 그것을 따르지 않습니다: 변경되는 구성 요소는 업데이트에 필요한 유지 관리를 인코딩하며, tokensave는 다음 시작 시 자동으로 수행합니다 — 수동으로 재설치나 재인덱스를 실행할 필요가 없습니다.

전역 재설치. 새 마이너 또는 메이저 빌드의 첫 실행 시, tokensave는 등록된 각 에이전트에 대해 install를 자동으로 다시 실행하므로 에이전트 구성이 항상 현재 바이너리를 가리키고 현재 도구 세트를 노출합니다. 패치 범프는 이 단계를 건너뜁니다 — 실행 중인 버전 표시만 진행됩니다.

재설치는 진정으로 조용합니다: 명시적 tokensave install에서 보는 에이전트별 설정 출력은 여기서 억제되므로 일반 tokensave init 또는 tokensave sync 앞에 나타나지 않습니다. 에이전트 구성을 새로 고칠 수 없는 경우 — 앱이 설치되지 않았거나 구성이 읽기 전용 위치에 있는 경우 — 실패한 에이전트 이름을 한 줄로 표시합니다:

warning: could not refresh tokensave config for: copilot.
  Run tokensave install to see the error.

tokensave install을 실행하여 기본 오류를 확인하세요. 버전 표시는 어느 쪽이든 진행되므로, 쓸 수 없는 구성 경로는 이후 모든 명령에서 재시도하는 대신 업그레이드당 한 번 보고됩니다.

프로젝트별 강제 재인덱스 (메이저 전용). 메이저 범프는 프로젝트 인덱스를 다시 빌드해야 함을 의미합니다. tokensave는 이를 지연 방식으로 프로젝트별로 수행합니다: 메이저 업그레이드 후 프로젝트의 첫 번째 MCP 도구 호출 시, 도구 응답을 차단하지 않는 백그라운드 전체 재인덱스(tokensave sync --force와 동일)를 생성합니다.

Brew / cargo 폴백. tokensave upgrade 외부에서 바이너리를 교체하는 외부 업그레이드 — brew upgrade tokensave 또는 cargo install tokensave — 는 동일한 방식으로 감지됩니다: 실행 중인 버전이 설치를 수행한 마지막 버전보다 최신이면 자체 업그레이드 후와 마찬가지로 다음 시작 시 재설치가 실행됩니다.

tokensave가 SemVer에서 벗어나는 이유(버전에 유지 관리를 인코딩하는 것이 무중단 업그레이드를 가능하게 함), 표시 메커니즘, 독립적인 데이터베이스 스키마 버전, 릴리스 생성에 대한 유지 관리자 규칙은 TOKENSAVE-VERSIONING.md를 참조하세요.

CLI 참조

tokensave init [path]              # Initialize a new project (full index)
tokensave sync [path]              # Incremental sync (must be initialized first)
tokensave sync --force [path]      # Force a full re-index
tokensave sync --doctor [path]     # Sync and list added/modified/removed files
tokensave status [path]            # Show statistics + cost summary
tokensave status [path] --json     # Show statistics (JSON output)
tokensave status --details         # Include node-kind breakdown
tokensave cost [range]             # Token cost summary (default: 7d)
tokensave cost --by-model          # Cost grouped by model
tokensave cost --by-task           # Cost grouped by task category
tokensave cost --export json|csv   # Export cost data
tokensave query <search> [path]    # Search symbols
tokensave files [--filter dir] [--pattern glob] [--json]   # List indexed files
tokensave affected <files...> [--stdin] [--depth N]        # Find affected test files
tokensave install [--agent NAME]   # Configure agent integration
tokensave reinstall                # Refresh settings for all installed agents
tokensave uninstall [--agent NAME] # Remove agent integration
tokensave serve [--idle-timeout-secs N]   # Start MCP server (N: exit after N idle seconds)
tokensave servers [--json]         # List running servers and the index each one holds
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave memory [--clean]         # Per-instance RSS report for all tokensave processes
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
tokensave githooks [on|off] [--local]  # Manage git hooks (--local: this repo only, no core.hooksPath)
tokensave branch add|list|remove|removeall|gc   # Multi-branch management
tokensave current-counter          # Show per-project token counter
tokensave reset-counter            # Reset per-project token counter
tokensave disable-upload-counter   # Opt out of worldwide counter uploads
tokensave enable-upload-counter    # Re-enable worldwide counter uploads

tokensave doctor

tokensave 설치에 대한 포괄적인 상태 검사를 실행합니다:

tokensave doctor

검사 항목: 바이너리 위치, 프로젝트 인덱스, 전역 DB, 사용자 구성, 에이전트 통합(MCP 서버, 훅, 권한, 프롬프트 규칙), 네트워크 연결. 업그레이드 후 도구 권한이 누락된 경우 tokensave install을 실행하라고 알려줍니다. 특정 에이전트만 확인하려면 --agent을 사용하세요.

Doctor는 또한 각 설치된 훅이 올바른 tokensave 하위 명령을 사용하는지 검증하고 손상된 훅을 자동으로 복구합니다.

Claude Code와의 작동 방식

구성 후, Claude Code는 코드베이스를 이해해야 할 때 원시 파일을 읽는 대신 자동으로 tokensave를 사용합니다. 세 가지 계층이 서로를 강화합니다:

결과: Claude는 훨씬 적은 토큰으로 동일한 코드 이해를 얻습니다. 일반적인 Explore 에이전트는 20-50개 파일을 읽습니다; tokensave는 사전 구축된 인덱스에서 관련 기호, 관계 및 코드 스니펫을 반환합니다.

네트워크 호출 및 개인정보 보호

tokensave의 핵심 기능(인덱싱, 검색, 그래프 쿼리, MCP 서버)은 100% 로컬입니다 — 코드가 머신을 떠나지 않습니다.

전 세계 카운터 업로드는 {"amount": 4823}와 같은 JSON 본문으로 단일 HTTP POST를 보냅니다. 쿠키 없음, 추적 없음, 사용자 ID 없음. Cloudflare Worker는 집계 지리 통계를 위해 IP 주소의 국가(요청 헤더에서 파생)를 기록합니다 — 실제 IP 주소는 저장되지 않습니다.

모델 가격 새로 고침은 GitHub에서 공개 JSON 파일(raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json)을 가져와 tokensave cost에 대한 Claude 모델 가격을 최신 상태로 유지합니다. 데이터는 전송되지 않습니다 — 일반 HTTPS GET입니다. 응답은 ~/.tokensave/pricing.json에 24시간 동안 캐시됩니다. 가져오기가 실패하면 tokensave는 컴파일된 가격 테이블을 사용합니다.

50개 이상의 언어

tokensave는 Cargo 기능 플래그로 제어되는 세 가지 계층으로 구성된 50개 이상의 프로그래밍 언어를 지원합니다. 각 계층은 아래 계층의 모든 언어를 포함합니다. Markdown 헤더는 계층적 Contains 에지가 있는 Module 노드로 추출되어 문서 구조가 소스 코드와 함께 그래프 쿼리에 참여합니다.

Lite -- --no-default-features

항상 컴파일됩니다. 가장 인기 있는 언어를 위한 가장 작은 바이너리와 Svelte 및 Astro(스크립트 블록 추출은 TypeScript 추출기를 통해, 추가 문법 종속성 없음).

Medium (Lite + 9개 추가) -- --features medium

전체 (중간 + 기타 모든 것) -- 기본값

개별 언어는 전체 티어 없이도 선택적으로 추가할 수 있습니다:

cargo install tokensave --no-default-features --features lang-nix,lang-bash

모든 추출기는 동일한 깊이를 공유합니다: 함수, 클래스, 메서드, 필드, 임포트, 호출 그래프, 상속 체인, docstring, 복잡도 메트릭, 데코레이터/어노테이션 추출, 그리고 파일 간 의존성 추적.

tokensave vs CodeGraph

tokensave는 CodeGraph (Node.js/TypeScript)의 처음부터 다시 작성된 Rust 버전입니다. 둘 다 AI 코딩 에이전트를 위한 의미론적 코드 그래프를 구축하지만, 범위와 기능에서 크게 차이가 있습니다.

CodeGraph는 이 접근 방식을 개척했으며 npm 도구를 선호하고 Claude Code 통합만 필요한 경우 여전히 견고한 선택입니다. tokensave는 더 깊은 분석, 더 많은 에이전트, 멀티 브랜치 지원, 그리고 런타임 의존성이 없는 네이티브 바이너리로 개념을 확장합니다.

CodeGraph, Dual-Graph (GrapeRoot), code-review-graph, OpenWolf와의 자세한 비교는 docs/COMPARABLE-TOOLS.md를 참조하세요.

대안보다 tokensave를 선택해야 하는 이유

여러 도구가 AI 코딩 에이전트의 토큰 사용량을 줄입니다. tokensave가 차별화되는 이유는 다음과 같습니다.

단일 네이티브 바이너리, 제로 의존성

모든 대안은 런타임이 필요합니다: Python, Node.js 또는 둘 다. tokensave는 모든 50+ tree-sitter 문법이 번들된 단일 약 25 MB Rust 바이너리로 제공됩니다. 설치할 것이 더 없습니다.

가장 깊은 코드 인텔리전스

tokensave는 심볼 수준에서 작동합니다: 함수, 구조체, 필드, 호출 엣지, 타입 계층, 복잡도 메트릭. Dual-Graph (GrapeRoot) 같은 대안은 파일 수준에서 작동합니다 -- 어떤 파일이 존재하는지 알지만 "이 함수를 누가 호출하나요?" 또는 "이 구조체를 변경하면 무엇이 깨지나요?"에 답할 수 없습니다. tokensave의 80+ 특수 MCP 도구는 호출 그래프 탐색, 영향 분석, 죽은 코드 감지, 테스트 매핑, 이름 변경 미리보기, 타입 계층, 순환 의존성 감지, 복잡도 순위, 코드 건강 분석 (Gini, DSM, 의존성 깊이, 위험 가중 테스트 격차), 원자적 편집 프리미티브 등을 다룹니다. 가장 가까운 경쟁자 (code-review-graph)는 22개의 도구를 보유하고 있으며, 다른 도구는 5-9개입니다.

가장 넓은 에이전트 지원

12개 이상의 AI 코딩 에이전트 통합과 에이전트별 네이티브 구성 형식을 제공합니다. 다른 도구는 이렇게 많은 에이전트를 이렇게 깊이 통합하지 못합니다. Claude Code는 훅, 프롬프트 규칙, 자동 허용 도구 권한을 얻습니다. Kiro는 전역 MCP 구성, 리소스로 로드되는 tokensave.md 스티어링, 허용적인 내장/tokensave 도구 승인을 가진 관리형 에이전트, 위임 가드레일 및 사후 쓰기 동기화를 위한 훅을 얻습니다. 다른 에이전트는 네이티브 구성 형식으로 MCP 서버 등록을 얻습니다.

멀티 브랜치 인덱싱

이 공간에서 선택적 브랜치별 그래프 데이터베이스와 브랜치 간 diff 및 검색을 제공하는 유일한 도구입니다. 활성화하면 브랜치 전환이 즉시 이루어집니다 -- 재인덱싱이 필요 없습니다.

호출별 토큰 추적

각 개별 MCP 도구 호출이 정확히 몇 토큰을 절약했는지 보고하는 유일한 도구이며, 모든 프로젝트에 걸친 실시간 TUI 모니터와 수명 카운터도 제공합니다.

완전 오픈 소스

MIT 라이선스 Rust, 종단 간 감사 가능. Dual-Graph의 핵심 엔진 (PyPI의 graperoot)은 독점입니다 -- 코드 그래프로 무엇을 하는지 볼 수 없습니다. OpenWolf는 AGPL-3.0으로 파생 작업을 오픈 소스로 공개해야 합니다.

성능

1,782개 파일의 혼합 Rust/Java/Scala 코드베이스 (57K 노드, 103K 엣지)에 대한 전체 인덱스 벤치마크:

문제 해결

"tokensave not initialized"

프로젝트에 .tokensave/ 디렉토리가 없습니다.

tokensave init

MCP 서버가 연결되지 않음

AI 에이전트가 tokensave 도구를 볼 수 없습니다.

1. 에이전트 구성에 tokensave MCP 서버가 포함되어 있는지 확인하세요 (tokensave doctor 실행)
2. 에이전트를 완전히 다시 시작하세요
3. tokensave가 PATH에 있는지 확인하세요: which tokensave

검색에서 누락된 심볼

• 인덱스를 업데이트하려면 tokensave sync 실행
• 언어가 지원되는지 확인하세요 (위 표 참조)
• 파일이 .gitignore에 의해 제외되지 않았는지 확인하세요

인덱싱이 느림

대규모 프로젝트는 첫 번째 전체 인덱스에 더 오래 걸립니다.

• 이후 실행은 증분 동기화를 사용하며 훨씬 빠릅니다
• 일상적인 업데이트에는 tokensave sync (--force 아님) 사용
• 에이전트가 연결된 동안 모든 MCP 도구 호출에서 오래됨이 자동으로 확인됩니다

특정 프로젝트에 대해 tokensave 비활성화

프로젝트가 너무 크고 tokensave가 너무 많은 RAM을 사용하는 경우, 환경에서 TOKENSAVE_DISABLE_SERVER=true를 설정하여 프로젝트별로 MCP 서버를 비활성화할 수 있습니다. 서버는 초기화 없이 깨끗하게 종료됩니다.

Claude Code — 프로젝트의 .claude/settings.json에 추가:

{
  "mcpServers": {
    "tokensave": {
      "command": "tokensave",
      "args": ["serve"],
      "env": {
        "TOKENSAVE_DISABLE_SERVER": "true"
      }
    }
  }
}

다른 에이전트 — 에이전트가 MCP 서버를 시작하는 데 사용하는 구성에 환경 변수를 설정하세요.

셸을 통해 전역으로 설정할 수도 있지만 (TOKENSAVE_DISABLE_SERVER=true claude), 이렇게 하면 세션의 모든 프로젝트에서 tokensave MCP 서버가 비활성화됩니다.

DISABLE_TOKENSAVE=true는 이 변수가 네임스페이스되기 전에 생성된 구성에 대한 더 이상 사용되지 않는 호환 별칭으로 계속 지원됩니다.

기원

이 프로젝트는 @colbymchenry의 원래 CodeGraph TypeScript 구현의 Rust 포트입니다. 포트는 동일한 아키텍처와 MCP 도구 인터페이스를 유지하면서 성능과 네이티브 tree-sitter 바인딩을 위해 Rust를 활용합니다.

빌드

cargo build --release                          # full (50+ languages, default)
cargo build --release --features medium        # medium tier
cargo build --release --no-default-features    # lite (smallest binary)

cargo test                                     # run all tests (requires full)
cargo check --no-default-features              # verify lite compiles
cargo clippy --all

스타 기록

스폰서

Windows용 무료 코드 서명은 SignPath.io에서 제공하며, 인증서는 SignPath Foundation에서 제공합니다.

라이선스

MIT 라이선스 -- 자세한 내용은 LICENSE를 참조하세요.

tokensave.dev