tokensave

Trí tuệ mã nguồn ngữ nghĩa cho các tác nhân mã hóa AI

Ít token hơn • Ít lệnh gọi công cụ hơn • 100% cục bộ

Tại sao chọn tokensave?

Các tác nhân mã hóa AI lãng phí token khi khám phá mã nguồn. Mỗi lần grep, glob, và đọc tệp đều tốn chi phí. Trong các tác vụ phức tạp, các tác nhân tạo ra nhiều tác nhân con Explore quét hàng trăm tệp chỉ để xây dựng ngữ cảnh.

tokensave cung cấp cho các tác nhân một đồ thị tri thức ngữ nghĩa được lập chỉ mục sẵn. Thay vì quét tệp, tác nhân truy vấn đồ thị và nhận được câu trả lời có cấu trúc tức thì -- các ký hiệu chính xác, mối quan hệ của chúng, và mã nguồn, trong một lần gọi.

Cách hoạt động

┌──────────────────────────────────────────────────────────────┐
│  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       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

Không có tokensave: Các tác nhân sử dụng grep, glob, và Read để quét tệp -- nhiều lệnh gọi API, tiêu tốn nhiều token.

Với tokensave: Các tác nhân truy vấn đồ thị thông qua các công cụ MCP -- kết quả tức thì, xử lý cục bộ, ít token hơn.

Các tính năng chính

Bắt đầu nhanh

1. Cài đặt

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 (mọi nền tảng):

# 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)

Tệp nhị phân dựng sẵn (Linux, Windows, macOS):

Tải xuống từ bản phát hành mới nhất và đặt tệp nhị phân vào PATH của bạn.

2. Cấu hình tác nhân của bạn

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

Mỗi tác nhân đăng ký máy chủ MCP của nó trong định dạng cấu hình gốc. Claude Code cũng nhận được hook PreToolUse (chặn các tác nhân Explore lãng phí), hook UserPromptSubmit, hook Stop, quy tắc nhắc trong CLAUDE.md, và quyền công cụ tự động cho phép. Kiro nhận cấu hình MCP toàn cục, tokensave.md điều hướng được tải như tài nguyên, và tác nhân mặc định do tokensave quản lý với phê duyệt công cụ tích hợp/tokensave linh hoạt, hook bảo vệ ủy quyền, và đồng bộ sau ghi; các tác nhân Kiro do người dùng quản lý được giữ nguyên.

Cài đặt OMP toàn cục nhắm vào hồ sơ được báo cáo bởi omp config path trần, ghi <resolved-agent-dir>/mcp.json và <resolved-agent-dir>/rules/tokensave.md. Xuất OMP_PROFILE hoặc PI_PROFILE tương thích của OMP khi cài đặt vào hồ sơ có tên; trình phân giải của OMP cũng tôn trọng PI_CONFIG_DIR và PI_CODING_AGENT_DIR. Tokensave tin tưởng trình phân giải gốc đó thay vì sao chép logic hồ sơ của OMP. Tokensave cài đặt MCP và quy tắc tư vấn cho OMP; nó không cài đặt thực thi hook OMP.

Tất cả các thay đổi đều idempotent -- an toàn để chạy lại sau khi nâng cấp. Sau khi thiết lập tác nhân, bạn sẽ được đề nghị hook git post-commit và post-checkout toàn cục. tokensave uninstall xóa các hook đó cùng với các tích hợp tác nhân; truyền --keep-git-hooks để giữ chúng, hoặc quản lý chúng riêng với tokensave githooks.

Cài đặt cục bộ dự án

Theo mặc định tokensave install đăng ký máy chủ MCP trong cấu hình tác nhân toàn cục của bạn (ví dụ: ~/.claude.json). Để đăng ký tokensave chỉ cho dự án hiện tại, thêm --local:

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

Điều này ghi cấu hình phạm vi dự án mà bạn có thể cam kết và chia sẻ với nhóm của mình. Đối với Claude đó là ./.mcp.json, ./.claude/settings.json, và ./CLAUDE.md; OMP sử dụng ./.omp/mcp.json và ./.omp/rules/tokensave.md mà không gọi CLI OMP. Các tác nhân được hỗ trợ: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank (mỗi tác nhân ghi tệp dự án riêng, ví dụ: .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 cho plank). Các tác nhân khác không có cấu hình phạm vi dự án và báo lỗi với --local.

Xóa cài đặt cục bộ dự án với tokensave uninstall --local.

3. Lập chỉ mục dự án của bạn

cd /path/to/your/project
tokensave init

Điều này tạo thư mục .tokensave/ với cơ sở dữ liệu đồ thị tri thức. Khởi tạo và đồng bộ là các lệnh riêng biệt: init là lựa chọn tham gia một lần cho mỗi dự án, trong khi sync chỉ cập nhật các dự án đã được khởi tạo. Điều này ngăn các hook git toàn cục âm thầm tạo cơ sở dữ liệu trong các kho lưu trữ bạn không bao giờ có ý định lập chỉ mục. Sau init, sử dụng tokensave sync để cập nhật gia tăng -- chỉ các tệp đã thay đổi được lập chỉ mục lại.

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

Đồng bộ chống sự cố

Các ngữ pháp tree-sitter là mã C/C++ được biên dịch. Chúng đôi khi gặp phải khẳng định nội bộ hoặc kết thúc tiến trình theo cách mà xử lý panic của Rust không thể chặn. Kể từ v4.3.0, mỗi tệp được phân tích bên trong một tiến trình con worker ngắn hạn: nếu ngữ pháp segfault, gọi abort(), hoặc gặp tràn ngăn xếp, chỉ worker chết. Nhóm khởi động lại nó, tệp gây lỗi được ghi log và bỏ qua, và sync tiếp tục.

Worker là một lệnh con extract-worker ẩn được xác thực với tiến trình cha qua token 256-bit cho mỗi lần sinh, được yêu cầu cả như biến môi trường TOKENSAVE_WORKER_TOKEN và là 32 byte đầu tiên nhận trên stdin. Gọi trực tiếp bởi người dùng sẽ thất bại. Mặc định là available_parallelism() worker; chọn không tham gia với TOKENSAVE_DISABLE_SUBPROCESS=1.

Các nguyên hàm chỉnh sửa (tokensave_str_replace, tokensave_insert_at, v.v.) vẫn chạy trong tiến trình: chúng nhắm vào một tệp tại một thời điểm nơi chi phí tiến trình con sẽ chiếm ưu thế, và sự cố trình trích xuất ở đó hiển thị ngay cho tác nhân.

Lập chỉ mục đa nhánh (Tùy chọn)

tokensave có thể tùy chọn duy trì một đồ thị mã riêng cho mỗi nhánh git. Khi được bật, chuyển đổi nhánh không bao giờ cho kết quả cũ và không bao giờ lập chỉ mục lại các tệp bạn đã phân tích trên nhánh khác. Theo dõi đa nhánh là tùy chọn -- nếu không có nó, tokensave sử dụng một cơ sở dữ liệu duy nhất cho tất cả các nhánh.

Cách hoạt động

Khi bạn theo dõi một nhánh, tokensave sao chép cơ sở dữ liệu tổ tiên gần nhất và đồng bộ chỉ các tệp khác nhau. Điều này có nghĩa là theo dõi một nhánh tính năng từ main gần như tức thì -- nó chỉ phân tích các tệp bạn đã thay đổi.

Lệnh 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

Công cụ MCP chéo nhánh

Ba công cụ MCP cho phép truy vấn chéo nhánh mà không cần chuyển đổi bản sao làm việc của bạn:

• tokensave_branch_search -- tìm kiếm ký hiệu trong đồ thị của nhánh khác
• tokensave_branch_diff -- so sánh đồ thị mã giữa hai nhánh: ký hiệu được thêm, xóa, và thay đổi (chữ ký khác nhau). Hỗ trợ bộ lọc tệp và loại.
• tokensave_branch_list -- liệt kê các nhánh được theo dõi với kích thước cơ sở dữ liệu, nhánh cha, và thời gian đồng bộ

Dự phòng nhánh

Khi máy chủ MCP không thể tìm thấy cơ sở dữ liệu cho nhánh hiện tại, nó phục vụ từ cơ sở dữ liệu của nhánh tổ tiên gần nhất và bao gồm cảnh báo trong mọi phản hồi công cụ đề xuất bạn chạy tokensave branch add.

Theo dõi nhánh tự động (v7.3.0)

Khi chế độ đa nhánh được khởi động (một tokensave branch add thủ công đầu tiên đã tạo siêu dữ liệu nhánh), các nhánh mới có thể được theo dõi tự động thay vì dự phòng vào cơ sở dữ liệu tổ tiên. Hai cơ chế độc lập bao phủ điều này; các dự án ở chế độ cơ sở dữ liệu đơn không bao giờ bị ảnh hưởng, và không cơ chế nào chạm vào cơ sở dữ liệu của nhánh mặc định. Git hook (khi chuyển nhánh). Hook post-checkout mà tokensave install thiết lập nhận diện việc chuyển nhánh (khác với chuyển tệp) và chạy tokensave branch add trong nền. Lệnh đó không làm gì khi nhánh đã được theo dõi hoặc là nhánh mặc định, vì vậy việc chuyển đổi thông thường giữa các nhánh đã biết không tốn chi phí. Lần checkout ban đầu của một git clone mới và của một git worktree add mới cũng là một lần chuyển nhánh, và nó có thể rơi vào một nhánh không phải là nhánh mặc định (git clone -b feature, git worktree add -b feature); ở đó hook chạy tokensave init trước và tokensave branch add sau, theo đúng thứ tự đó. Một hook được viết bởi phiên bản trước đó giữ nguyên phần thân mà nó được cài đặt — trình cài đặt không bao giờ ghi đè lên hook hiện có — vì vậy trên những bản cài đặt đó, một worktree mới vẫn cần auto_track bên dưới, hoặc một lệnh tokensave branch add thủ công.

Tự động theo dõi khi mở (tùy chọn). Khi TokenSave::open chạy — lệnh CLI hoặc khởi động máy chủ MCP — và nhánh đang hoạt động chưa được theo dõi, tokensave có thể theo dõi nó ngay tại chỗ bằng cách sao chép DB của tổ tiên được theo dõi gần nhất và ghi lại vào siêu dữ liệu nhánh. Điều này được kiểm soát bởi trường cấu hình auto_track (mặc định false) hoặc biến môi trường TOKENSAVE_AUTO_TRACK, biến này ghi đè cấu hình cho mỗi lần chạy (bất kỳ giá trị nào cũng kích hoạt nó ngoại trừ 0, false, no, off, hoặc để trống). Bản sao này là bản sao DB tổ tiên gần như tức thì giống như lệnh branch add thủ công thực hiện; không có đồng bộ nào chạy tại thời điểm đó — hook post-commit giữ cho DB nhánh mới luôn mới khi bạn commit, hoặc chạy tokensave sync để làm mới ngay lập tức. Tự động theo dõi hoàn toàn là nỗ lực tốt nhất: bất kỳ lỗi nào cũng được báo cáo dưới dạng cảnh báo và open() tiếp tục với cơ chế dự phòng tổ tiên thông thường, vì vậy nó không bao giờ làm hỏng một lệnh gọi công cụ.

Tóm lại: với hook được cài đặt, việc checkout một nhánh tính năng mới — bao gồm cả nhánh mà một bản clone hoặc worktree mới bắt đầu — một cách minh bạch sẽ cấp cho nó đồ thị riêng theo từng nhánh; với auto_track được bật, ngay cả một nhánh được tạo bên ngoài một lần checkout cũng sẽ được nhận diện lần đầu tiên tokensave mở dự án trên đó.

Xem docs/BRANCHING-USER-GUIDE.md để có hướng dẫn đầy đủ.

Bộ nhớ xuyên phiên

Ba công cụ MCP lưu trữ các quyết định và ngữ cảnh vùng mã qua các phiên, được lưu trong .tokensave/tokensave.db theo từng dự án.

Sử dụng những công cụ này để agent không phải giải thích lại các lựa chọn kiến trúc giữa các phiên.

Sổ cái tiết kiệm

Mỗi lần gọi MCP ghi một hàng chỉ nối thêm vào ~/.tokensave/global.db (bảng savings_ledger). Kiểm tra bằng tokensave gain:

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

Ước tính đô la sử dụng mô-đun định giá hiện có (định giá đầu vào Sonnet, làm mới hàng ngày qua LiteLLM).

Benchmark tái lập

tokensave bench chạy một bộ truy vấn cố định qua tokensave_context và báo cáo mức tiết kiệm truy xuất so với đường cơ sở toàn tệp (phản ánh phương pháp CCE):

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

Đo trên repo này (chính tokensave) bằng bộ truy vấn chung được cung cấp:

Tổng hợp: 88% tiết kiệm truy xuất trung bình (142.8k → 5.5k token trên 10 truy vấn).

Bộ truy vấn mặc định nhắm vào các mẫu có trong hầu hết các codebase ứng dụng (CLI, daemon, dịch vụ). Chạy nó trên dự án của riêng bạn với tokensave bench để xem số liệu của bạn, hoặc viết một tệp truy vấn tùy chỉnh (--queries my.toml) để thu hồi chặt chẽ hơn.

Benchmark criterion trên các repo thực tế lớn

benches/large_repos.rs là một micro-benchmark criterion chạy các công cụ MCP từ đầu đến cuối trên bốn codebase nguồn mở lớn được ghim ở các ref cố định. Mỗi công cụ được điều khiển bởi ít nhất 5 truy vấn với các đối số (id nút, tên đủ điều kiện, glob tệp, …) được lấy mẫu từ đồ thị đã lập chỉ mục một lần cho mỗi repo, vì vậy thời gian có thể tái lập giữa các lần chạy.

Repo và ref được ghim (được định nghĩa trong benches/repos.rs):

Mỗi repo được shallow-clone (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) khi sử dụng lần đầu và được lưu cache cục bộ; các lần chạy sau tái sử dụng checkout. Đầu ra Git được truyền trực tiếp đến terminal để quá trình tải nhiều GB hiển thị tiến trình theo thời gian thực.

Các công cụ được bao phủ (5 truy vấn mỗi công cụ). Công cụ đọc — 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. Công cụ ghi — str_replace, multi_str_replace, insert_at, và (nếu ast-grep được bật trên PATH) ast_grep_rewrite.

Đồng bộ cưỡng bức mỗi lần chạy. Trước khi bất kỳ benchmark nào chạy, bộ khung chạy tương đương với tokensave sync --force trên mỗi repo (index_all() bất kể độ mới của .tokensave/) để thời gian luôn phản ánh nguồn được ghim.

Benchmark ghi và dọn dẹp. Công cụ ghi thay đổi tệp. Để giữ điều kiện tiên quyết "khớp phải là duy nhất", bộ khung sử dụng iter_batched của criterion — một tệp scratch nhỏ dưới <repo>/.tokensave-bench-scratch/ được ghi lại với nội dung đã biết trước mỗi lần lặp có thời gian, sau đó công cụ chỉnh sửa chạy trên nó. Sau khi tất cả benchmark hoàn tất, bộ khung chạy git stash --include-untracked && git stash drop bên trong mỗi repo đã chuẩn bị để cây làm việc trở về ref được ghim.

Cấu hình criterion. Benchmark ghi đè các mặc định của criterion thành sample_size = 10 và measurement_time = 30s (so với 100 / 5s tiêu chuẩn), điều này cho mỗi thời gian truy vấn khoảng 30 giây đo lường — đủ để các công cụ chậm như tokensave_context trên polkadot-sdk tạo ra số liệu ổn định.

Chạy nó:

# 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

Nếu TOKENSAVE_BENCH_REPOS_DIR không được đặt, benchmark in một thông báo và đăng ký không benchmark nào (vì vậy cargo bench --all vẫn rẻ trên máy của người đóng góp).

Cấu hình (tất cả tùy chọn, qua môi trường):

Lọc benchmark sử dụng CLI criterion tiêu chuẩn — ví dụ, chỉ công cụ search trên scipy:

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

Báo cáo (HTML + mẫu thô) nằm dưới target/criterion/.

Để thay đổi ref được ghim (ví dụ đến một bản phát hành mới hơn hoặc một SHA cụ thể), chỉnh sửa REPOS trong benches/repos.rs và xóa marker $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref tương ứng để lần chạy tiếp theo tải lại. Nếu bạn bỏ qua việc dọn dẹp sau khi chạy (ví dụ bạn Ctrl-C giữa benchmark), chạy git stash --include-untracked && git stash drop bên trong mỗi thư mục repo để khôi phục thủ công.

Probe ma trận kiểm thử MCP (scripts/mcp_probe)

scripts/mcp_probe/ là một bộ khung Python điều khiển tokensave serve qua stdio trên một tập repo thực tế có thể cấu hình và thực hiện mọi công cụ MCP chỉ đọc với 5 biến thể truy vấn cho mỗi ngôn ngữ, tạo ra một bảng trạng thái theo công cụ / theo repo. Cùng một bộ khung phục vụ hai mục đích:

• Quét hồi quy. Hỗ trợ ngôn ngữ mới, công cụ mới hoặc tái cấu trúc — chạy lại ma trận và bất kỳ ô nào mới lỗi, hết thời gian hoặc trả về kết quả trống sẽ nổi bật với 🚩.
• Probe hiệu suất. Thời gian mỗi lần gọi được ghi trong TSV; cùng một kho ngữ liệu cố định đóng vai trò là so sánh thô giữa các phiên bản. Chu kỳ lỗi tokensave_inheritance_depth hiện tại được tìm thấy bởi bộ khung này khi một công cụ duy nhất trên polkadot-sdk hết thời gian ở >60 giây.

Bố cục — probe.py là trình điều khiển (JSON-RPC khớp id để một công cụ chậm không thể làm hỏng các lần gọi sau), isolated.py chạy lại một công cụ duy nhất với một máy chủ mới cho mỗi lần gọi (tránh xếp hàng máy chủ), build_matrix.py đọc TSV và phát ra markdown, các mô-đun tools/<lang>.py đóng góp bộ truy vấn theo ngôn ngữ (Rust được cung cấp; thêm Python/Go/… bằng cách thêm một mô-đun mới), repos.toml liệt kê các repo mục tiêu (ghi đè qua $TOKENSAVE_PROBE_REPOS).

Chạy nhanh:

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

Các ô đầu ra là ✓ 5/5 (sạch), 🐛 e/N (lỗi), ⏱ N/N (hết thời gian), ∅ E/N (trống), 🐢 ok/slow (>10 giây gọi). Bất kỳ ô nào có lỗi hoặc hết thời gian sẽ nhận 🚩 trong cột ngoài cùng bên phải. Chi tiết mỗi lần gọi với 100 ký tự đầu tiên của mỗi lỗi được ghi trong log TSV để theo dõi.

Khác với benchmark criterion ở trên: criterion đo độ trễ mỗi lần lặp cho một tập công cụ tập trung trên các ref được ghim và tạo báo cáo thống kê dưới target/criterion/; mcp_probe thực hiện mọi công cụ với một bộ truy vấn rộng hơn trên bất kỳ repo nào bạn trỏ tới, tối ưu hóa cho độ bao phủ rộng thay vì độ chính xác đo lường.

80+ Công cụ MCP

Máy chủ hiển thị hơn 80 công cụ (ít hơn một khi tệp nhị phân tùy chọn ast-grep không có trên PATH); các bảng bên dưới nhóm các công cụ được sử dụng phổ biến nhất theo danh mục. Hầu hết là chỉ đọc, an toàn để gọi song song và được chú thích bằng readOnlyHint. Các nguyên hàm chỉnh sửa được giới hạn trong các tệp đơn và lập chỉ mục lại tại chỗ; các công cụ ghi baseline phiên và ghi nhớ cũng thay đổi trạng thái .tokensave cục bộ và được chú thích là không chỉ đọc. Ba công cụ cốt lõi (tokensave_context, tokensave_search, tokensave_status) được đánh dấu anthropic/alwaysLoad để chúng bỏ qua vòng lặp tìm kiếm công cụ của máy khách.

Truy vấn một dự án đã khởi tạo khác

Các công cụ đọc ngữ nghĩa có thể truy vấn một đồ thị cục bộ được chọn rõ ràng mà không cần khởi động lại máy chủ MCP:

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

Kết quả được chọn bao gồm nguồn gốc root/nhánh chuẩn. ID nút được đặt tên theo không gian của đồ thị đó và các bộ chọn khớp phải được lặp lại trong các lần gọi tiếp theo. Ví dụ, một lần gọi tiếp theo cho một truy vấn đã chọn nhánh bao gồm cả hai giá trị:

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

graph_root phải là root tuyệt đối chính xác của một dự án đã được khởi tạo. graph_branch là tùy chọn và, khi được cung cấp, phải đặt tên một nhánh được theo dõi. Các lần mở được chọn là chỉ đọc: chúng không bao giờ khởi tạo, đồng bộ, di chuyển, tự động theo dõi hoặc ghi dữ liệu đồ thị/nguồn. Chúng cũng không đóng góp vào kế toán tiết kiệm. Các lần gọi không có bộ chọn hoạt động chính xác như trước. graph_root chỉ hữu ích nếu bạn biết dự án khác tồn tại, vì vậy máy chủ cho bạn biết: các dự án đã khởi tạo nằm ngay bên cạnh thư mục gốc được phục vụ sẽ được nêu tên trong MCP instructions, trong tokensave_status, và trong các kết quả tokensave_search / tokensave_context trống — thời điểm mà một phiên nếu không sẽ kết luận một biểu tượng không tồn tại thay vì tìm kiếm bên cạnh (#375). Chỉ các dự án anh em trực tiếp được cung cấp, tối đa năm, và không có gì được mở hoặc lập chỉ mục thay mặt chúng; truy vấn một dự án vẫn yêu cầu một graph_root rõ ràng.

Bộ chọn cố tình không khả dụng trên các công cụ ghi, gọi shell, hoặc phụ thuộc vào bản checkout hiện tại: các nguyên hàm chỉnh sửa, công cụ VCS và nhánh, chẩn đoán và thực thi kiểm thử, kiểm tra phụ thuộc và runtime, quy trình làm việc và công cụ bộ nhớ phiên, công cụ bộ nhớ đệm bền vững (tokensave_redundancy), và quản trị máy chủ. Các công cụ đó từ chối bộ chọn thay vì âm thầm bỏ qua nó.

Khám phá

Tạo phẩm phi mã

tokensave_files bao phủ nhiều hơn mã nguồn. Các tệp có phần mở rộng được liệt kê trong artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md theo mặc định) được theo dõi theo đường dẫn để các câu hỏi như "các tệp .feature cho luồng đăng nhập ở đâu?" có câu trả lời dạng đồ thị thay vì một find bị chặn (#323). Chúng không bao giờ được phân tích cú pháp và không đóng góp biểu tượng nào; kind: "artifact" và kind: "code" lọc giữa hai loại, và các phân tích có nghĩa "mã" loại trừ chúng. Một phần mở rộng đã được xử lý bởi một trình trích xuất ngôn ngữ bị bỏ qua trong danh sách này, vì vậy nó không thể được sử dụng để ngăn một ngôn ngữ bị phân tích cú pháp.

Danh sách cũng quyết định tìm kiếm theo nghĩa đen có thể nhìn vào bên trong gì (#442). Một tìm kiếm theo nghĩa đen (literal: true) trên tokensave_search đọc byte thay vì biểu tượng, vì vậy nó không cần trình phân tích cú pháp -- nhưng nó lặp qua các tệp đã lập chỉ mục, vì vậy nó chỉ có thể truy cập một tệp mà chỉ mục có một hàng. Một mẫu .html được theo dõi hoặc biểu định kiểu .css không có trình trích xuất cũng như mục tạo phẩm mặc định, vì vậy các kết quả khớp của nó bị thiếu; thêm phần mở rộng ở đây và chạy tokensave sync -f và các dòng của nó được tìm kiếm như bất kỳ dòng nào khác, được báo cáo với enclosing: null vì không có ngữ cảnh biểu tượng. Một phản hồi theo nghĩa đen không thể truy cập mọi tệp được theo dõi sẽ nói rõ điều đó trong một khối unscanned nêu tên số lượng và các phần mở rộng, vì vậy một câu trả lời một phần không bao giờ được trình bày như một câu trả lời hoàn chỉnh.

Đồ thị Gọi & Tác động

Chất lượng Mã

Phân tích Sức khỏe Mã

Năm công cụ hiển thị tín hiệu chất lượng cấu trúc từ đồ thị hiện có. Điểm tổng hợp sử dụng trung bình hình học trên các chiều độc lập để không một chiều nào có thể bị thao túng.

Phiên

Chụp chỉ số sức khỏe tại thời điểm bắt đầu một phiên mã AI, sau đó so sánh khác biệt ở cuối để xem những gì đã cải thiện hoặc thoái lui.

Nguyên hàm Chỉnh sửa

Bốn công cụ ghi cho phép tác nhân sửa đổi tệp mà không gặp rủi ro regex hoặc trích dẫn shell. Mỗi công cụ là một tệp, được neo, và kích hoạt lập chỉ mục lại tại chỗ sau khi ghi để đồ thị không bao giờ lỗi thời.

Git & Quy trình làm việc

Hệ thống Kiểu

Chuyển đổi

Đa Nhánh

Tài nguyên MCP

Bốn tài nguyên được hiển thị qua resources/list và resources/read:

• tokensave://status -- thống kê đồ thị dưới dạng JSON
• tokensave://files -- cây tệp đã lập chỉ mục được nhóm theo thư mục
• tokensave://overview -- tóm tắt dự án với phân phối ngôn ngữ và loại biểu tượng
• tokensave://branches -- các nhánh được theo dõi với kích thước DB và thông tin cha

Theo dõi Token

tokensave đo lường các token mà nó lưu trên mỗi lần gọi công cụ MCP. Mỗi phản hồi công cụ bao gồm một dòng tokensave_metrics: before=N after=M hiển thị bao nhiêu token tệp thô đã được tránh bởi lần gọi cụ thể đó.

Tắt báo cáo. Dòng chỉ số, cùng với một câu trong MCP instructions, yêu cầu tác nhân báo cáo khoản tiết kiệm cho bạn — điều đó có nghĩa là mô hình chi token đầu ra để tường thuật một khoản tiết kiệm mà tokensave đã thực hiện trên token đầu vào. Token đầu ra là loại đắt hơn, vì vậy nếu tác nhân của bạn đề cập đến tokensave gần như mỗi lượt, việc tường thuật đó có thể bù đắp lợi ích (#356). Đặt report_savings thành false trong .tokensave/config.json, hoặc biến môi trường TOKENSAVE_REPORT_SAVINGS để ghi đè mỗi lần chạy (bất kỳ giá trị nào kích hoạt nó ngoại trừ 0, false, no, off, hoặc trống). Cả dòng chỉ số và hướng dẫn biến mất; tokensave install tương tự ngừng ghi quy tắc báo cáo vào các tệp lời nhắc tác nhân. Đo lường không bị ảnh hưởng trong cả hai trường hợp — mỗi lần gọi vẫn được ghi vào sổ cái tiết kiệm, vì vậy tokensave gain, tokensave list, status và monitor tiếp tục báo cáo chính xác như trước. Mặc định vẫn là true.

Quan sát chi phí

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

Phân tích cú pháp bản ghi phiên Claude Code (~/.claude/projects/**/*.jsonl), phân loại mỗi lượt API thành một trong 13 danh mục tác vụ, tính toán chi phí đô la bằng cách sử dụng giá mô hình, và lưu trữ kết quả trong ~/.tokensave/global.db cho các truy vấn tổng hợp nhanh. Giá được làm mới từ LiteLLM mỗi 24 giờ và dự phòng vào một bảng nhúng khi ngoại tuyến.

Tiêu đề tokensave status bao gồm một hàng chi phí hiển thị chi tiêu hôm nay, tổng 7 ngày, và tỷ lệ hiệu quả (token đã lưu / tổng token). TUI tokensave monitor hiển thị một bảng chi phí trực tiếp bên cạnh nguồn cấp tiết kiệm. Vào cuối mỗi phiên Claude Code, trình xử lý hook_stop in một biên nhận một dòng ra thiết bị đầu cuối.

Các danh mục phân loại tác vụ: Coding, Debugging, Feature Dev, Refactoring, Testing, Exploration, Planning, Delegation, Git Ops, Build/Deploy, Brainstorming, Conversation, General. Phân loại là xác định (khớp mẫu trên tên công cụ và lệnh Bash), không yêu cầu lời gọi LLM, và được điều chỉnh từ AgentSeal/codeburn.

Giám sát trực tiếp

tokensave monitor

Một TUI toàn cầu hiển thị các lời gọi công cụ MCP từ tất cả các dự án trong thời gian thực, qua một bộ đệm vòng bộ nhớ dùng chung được ánh xạ tại ~/.tokensave/monitor.mmap. Mỗi mục hiển thị tên dự án, tên công cụ, và delta token. Một bảng chi phí ở đầu hiển thị chi tiêu hôm nay, tiết kiệm, hiệu quả, và mô hình hàng đầu (làm mới mỗi 30 giây).

Chẩn đoán bộ nhớ

tokensave memory [--clean]

Báo cáo bộ nhớ trên toàn máy cho mọi tiến trình tokensave (MCP servers, syncs, index runs), thông qua một bảng ánh xạ bộ nhớ dùng chung tại ~/.tokensave/memory.mmap. Mỗi instance tự lấy mẫu RSS của chính nó ở mức best-effort khi khởi động, mỗi lần gọi công cụ MCP, và xung quanh các giai đoạn sync/resolution, để báo cáo hiển thị RSS hiện tại và đỉnh kèm giai đoạn tạo ra đỉnh đó — dữ liệu cần thiết để quy kết việc sử dụng bộ nhớ cao (xem #253). Các hàng được gắn cờ alive, dead (một tiến trình bị OOM-kill để lại peak/phase của nó như một bản ghi pháp y), hoặc orphan (vẫn đang chạy nhưng đã được reparent về init). --clean dọn dẹp các slot đã chết.

PEAK PHASE đặt tên cho mẫu cao nhất, vì vậy nó chỉ chính xác ở mức độ lấy mẫu. Bản ghi sync tăng dần, theo thứ tự: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. Một index đầy đủ ghi lại index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done.

Mỗi mẫu được ghi lại sau công việc mà nó đặt tên. Trước đây chúng được ghi trước công việc đó, vì vậy mọi mẫu đều báo cáo RSS của bước trước dưới nhãn của bước tiếp theo — điều này đã quy kết 73 MiB cho việc tải node mà thực ra thuộc về việc tải các tham chiếu chưa được giải quyết, một bước không có mẫu nào, và đã chỉ một cuộc điều tra bộ nhớ vào sai phân hệ trong nhiều tháng (#409). Nếu bạn thêm một giai đoạn, hãy lấy mẫu sau công việc, không phải trước nó, và thêm một mẫu cho bất kỳ bước nào đủ lớn để giữ đỉnh.

Bộ đếm phiên và vòng đời

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 hiển thị thống kê index của dự án, phân tích ngôn ngữ, hàng chi phí (hôm nay / 7 ngày / hiệu quả), và tổng vòng đời của dự án + toàn thế giới:

Bộ đếm toàn thế giới

Tất cả người dùng tokensave đóng góp vào một bộ đếm tổng hợp ẩn danh. tokensave status hiển thị cả tổng dự án của bạn và tổng toàn thế giới. Việc tải lên chỉ gửi một số duy nhất (ví dụ: 4823) mà không có thông tin nhận dạng. Từ chối với tokensave disable-upload-counter.

Độ tươi của Index

tokensave giữ đồ thị được cập nhật mà không cần daemon nền hoặc trình theo dõi tệp ở cấp hệ điều hành.

Kiểm tra độ cũ theo yêu cầu. Mỗi lần gọi công cụ MCP kiểm tra xem có tệp nào đã được index bị sửa đổi kể từ lần sync cuối không. Nếu tìm thấy tệp cũ, chúng được trích xuất lại trước khi trả về phản hồi công cụ. Thời gian chờ 30 giây ngăn các cuộc gọi liên tiếp quét lại cây trên mỗi lần gõ phím.

Sync bắt kịp khi kết nối. Khi máy chủ MCP khởi động, nó ngay lập tức chạy một sync bắt kịp không chặn để nhận mọi thay đổi được thực hiện khi không có agent nào được gắn — một git pull, chỉnh sửa IDE, bước build — để lần gọi công cụ đầu tiên của phiên thấy một index tươi.

Công việc đa agent và git worktrees. Khi nhiều agent làm việc trên cùng một dự án đồng thời, giả định mạnh là mỗi agent hoạt động trong worktree git riêng của nó. Worktrees là các bản checkout hệ thống tệp độc lập của cùng một kho lưu trữ: agent A và agent B mỗi agent có bản sao riêng của mọi tệp, vì vậy chúng không bao giờ ghi đè các chỉnh sửa đang thực hiện của nhau. tokensave tự động phát hiện khi một truy vấn đến từ một worktree lồng bên trong checkout chính và phục vụ kết quả từ đồ thị nhánh chính xác. Các thay đổi tích lũy độc lập và cuối cùng được hòa giải qua git merge hoặc rebase — cùng quy trình được sử dụng cho bất kỳ phát triển song song nào khác. Thiết kế này tránh sự phức tạp và các chế độ lỗi của việc khóa chéo agent trên một thư mục có thể thay đổi dùng chung.

Quy trình chỉ CLI. Nếu bạn chạy các lệnh tokensave mà không có agent được gắn (không có máy chủ MCP), kiểm tra độ cũ không chạy giữa các lệnh. Cài đặt git hooks để giữ index tươi tự động sau mỗi commit hoặc clone:

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

Nâng cấp từ 5.x

Lệnh độc lập tokensave daemon và tính năng tự động khởi động launchd/systemd/Windows Service của nó đã bị xóa trong 6.0.0. Trình theo dõi tệp cấp hệ điều hành nhúng thay thế daemon đã tự nó bị xóa trong 6.1.1 (nó gây CPU và bộ nhớ mất kiểm soát trên các monorepo lớn với cây node_modules hoặc target sâu). Mô hình kiểm tra độ cũ theo yêu cầu ở trên là thiết kế hiện tại.

Nếu bạn vẫn có tự động khởi động daemon từ 5.x, hãy xóa nó:

• 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 (từ terminal nâng cao)

Nếu bạn không nhớ tên chính xác: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

Tự nâng cấp

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 tải xuống binary nền tảng chính xác từ GitHub releases và thay thế binary đang chạy tại chỗ. Hỗ trợ các kênh stable và beta độc lập.

Phiên bản & nâng cấp

Số phiên bản tokensave trông giống SemVer nhưng không tuân theo nó: thành phần thay đổi mã hóa bảo trì mà bản cập nhật yêu cầu, mà tokensave thực hiện tự động ở lần khởi động tiếp theo — bạn không bao giờ chạy cài đặt lại hoặc reindex bằng tay.

Cài đặt lại toàn cầu. Ở lần chạy đầu tiên của một bản minor hoặc major mới, tokensave âm thầm chạy lại install cho mỗi agent mà nó đã đăng ký, để cấu hình agent luôn trỏ đến binary hiện tại và hiển thị bộ công cụ hiện tại. Patch bumps bỏ qua điều này — dấu phiên bản đang chạy chỉ đơn giản được nâng lên.

Việc cài đặt lại thực sự âm thầm: đầu ra thiết lập theo agent mà bạn thấy từ một tokensave install tường minh bị ẩn ở đây, vì vậy nó không bao giờ xuất hiện trước một tokensave init hoặc tokensave sync thông thường. Nếu cấu hình của một agent không thể làm mới — ứng dụng không được cài đặt, hoặc cấu hình của nó nằm ở nơi chỉ đọc — bạn nhận được một dòng đặt tên các agent bị lỗi:

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

Chạy tokensave install để xem lỗi cơ bản. Các dấu phiên bản tiến lên trong cả hai trường hợp, vì vậy một đường dẫn cấu hình không bao giờ có thể ghi được báo cáo một lần mỗi lần nâng cấp thay vì thử lại trên mọi lệnh tiếp theo.

Reindex bắt buộc theo dự án (chỉ major). Một bump major có nghĩa là các index dự án phải được xây dựng lại. tokensave thực hiện điều này một cách lười biếng và theo từng dự án: ở lần gọi công cụ MCP đầu tiên trong một dự án sau nâng cấp major, nó sinh ra một reindex đầy đủ nền (tương đương tokensave sync --force) không bao giờ chặn phản hồi công cụ.

Dự phòng Brew / cargo. Các nâng cấp bên ngoài thay thế binary ngoài tokensave upgrade — brew upgrade tokensave hoặc cargo install tokensave — được phát hiện theo cùng cách: nếu phiên bản đang chạy mới hơn phiên bản cuối cùng đã thực hiện cài đặt, việc cài đặt lại chạy ở lần khởi động tiếp theo giống như sau tự nâng cấp.

Xem TOKENSAVE-VERSIONING.md để biết lý do tokensave khác với SemVer (mã hóa bảo trì trong phiên bản là điều làm cho nâng cấp không cần chạm tay trở nên khả thi), cơ chế dấu, phiên bản schema cơ sở dữ liệu độc lập, và các quy tắc duy trì để cắt bản phát hành.

Tham chiếu 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

Chạy kiểm tra sức khỏe toàn diện của cài đặt tokensave của bạn:

tokensave doctor

Kiểm tra: vị trí binary, index dự án, DB toàn cầu, cấu hình người dùng, tích hợp agent (máy chủ MCP, hooks, quyền, quy tắc prompt), và kết nối mạng. Nếu bất kỳ quyền công cụ nào bị thiếu sau nâng cấp, nó bảo bạn chạy tokensave install. Sử dụng --agent để chỉ kiểm tra một agent cụ thể.

Doctor cũng xác thực rằng mỗi hook đã cài sử dụng đúng lệnh con tokensave và tự sửa chữa các hook bị hỏng.

Cách hoạt động với Claude Code

Khi được cấu hình, Claude Code tự động sử dụng tokensave thay vì đọc tệp thô khi cần hiểu codebase của bạn. Ba lớp củng cố lẫn nhau:

Kết quả: Claude có cùng sự hiểu biết mã với ít token hơn nhiều. Một Explore agent điển hình đọc 20-50 tệp; tokensave trả về các ký hiệu, mối quan hệ, và đoạn mã liên quan từ index được xây dựng sẵn của nó.

Gọi mạng & Quyền riêng tư

Chức năng cốt lõi của tokensave (indexing, tìm kiếm, truy vấn đồ thị, máy chủ MCP) là 100% cục bộ -- mã của bạn không bao giờ rời khỏi máy của bạn.

Việc tải lên bộ đếm toàn thế giới gửi một HTTP POST duy nhất với thân JSON như {"amount": 4823}. Không cookie, không theo dõi, không ID người dùng. Cloudflare Worker ghi lại quốc gia của địa chỉ IP của bạn (suy ra từ tiêu đề yêu cầu) cho thống kê địa lý tổng hợp -- địa chỉ IP thực tế của bạn không được lưu trữ.

Việc làm mới giá mô hình tải một tệp JSON công khai từ GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) để giữ giá mô hình Claude cập nhật cho tokensave cost. Không dữ liệu nào được gửi -- đó là một HTTPS GET đơn giản. Phản hồi được cache tại ~/.tokensave/pricing.json trong 24 giờ. Nếu tải thất bại, tokensave sử dụng bảng giá được biên dịch sẵn của nó.

50+ Ngôn ngữ

tokensave hỗ trợ hơn 50 ngôn ngữ lập trình được tổ chức thành ba tầng được kiểm soát bởi các cờ tính năng Cargo. Mỗi tầng bao gồm tất cả ngôn ngữ từ tầng bên dưới nó. Tiêu đề Markdown được trích xuất dưới dạng các nút Module với các cạnh Contains phân cấp để cấu trúc tài liệu tham gia vào các truy vấn đồ thị cùng với mã nguồn.

Lite -- --no-default-features

Luôn được biên dịch. Binary nhỏ nhất cho các ngôn ngữ phổ biến nhất, cộng với Svelte và Astro (trích xuất khối script qua trình trích xuất TypeScript, không có phụ thuộc grammar bổ sung).

Medium (Lite + 9 ngôn ngữ nữa) -- --features medium

Đầy đủ (Medium + mọi thứ khác) -- mặc định

Các ngôn ngữ riêng lẻ cũng có thể được chọn riêng mà không cần một tầng đầy đủ:

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

Tất cả các bộ trích xuất đều chia sẻ cùng độ sâu: hàm, lớp, phương thức, trường, import, đồ thị gọi, chuỗi kế thừa, docstring, chỉ số độ phức tạp, trích xuất decorator/chú thích, và theo dõi phụ thuộc giữa các tệp.

tokensave so với CodeGraph

tokensave là bản viết lại hoàn toàn bằng Rust từ CodeGraph (Node.js/TypeScript). Cả hai đều xây dựng đồ thị mã ngữ nghĩa cho các tác nhân mã hóa AI, nhưng chúng khác biệt đáng kể về phạm vi và khả năng.

CodeGraph đã tiên phong trong cách tiếp cận này và vẫn là lựa chọn vững chắc nếu bạn ưa thích công cụ npm và chỉ cần tích hợp Claude Code. tokensave mở rộng khái niệm với phân tích sâu hơn, nhiều tác nhân hơn, hỗ trợ đa nhánh và tệp nhị phân gốc không có phụ thuộc thời gian chạy.

Để so sánh chi tiết với CodeGraph, Dual-Graph (GrapeRoot), code-review-graph và OpenWolf, xem docs/COMPARABLE-TOOLS.md.

Tại sao chọn tokensave Thay vì Các Lựa Chọn Khác

Một số công cụ giảm mức sử dụng token cho các tác nhân mã hóa AI. Đây là lý do tokensave nổi bật.

Một tệp nhị phân gốc duy nhất, không phụ thuộc

Mọi lựa chọn thay thế đều yêu cầu một thời gian chạy: Python, Node.js hoặc cả hai. tokensave được phân phối dưới dạng một tệp nhị phân Rust ~25 MB duy nhất với tất cả 50+ ngữ pháp tree-sitter được đóng gói. Không cần cài đặt gì thêm.

Trí tuệ mã sâu nhất

tokensave hoạt động ở cấp độ ký hiệu: hàm, struct, trường, cạnh gọi, hệ thống phân cấp kiểu, chỉ số độ phức tạp. Các lựa chọn thay thế như Dual-Graph (GrapeRoot) hoạt động ở cấp độ tệp -- chúng biết tệp nào tồn tại nhưng không thể trả lời "ai gọi hàm này?" hoặc "điều gì hỏng nếu tôi thay đổi struct này?" 80+ công cụ MCP chuyên biệt của tokensave bao gồm duyệt đồ thị gọi, phân tích tác động, phát hiện mã chết, ánh xạ kiểm thử, xem trước đổi tên, hệ thống phân cấp kiểu, phát hiện phụ thuộc vòng, xếp hạng độ phức tạp, phân tích sức khỏe mã (Gini, DSM, độ sâu phụ thuộc, khoảng trống kiểm thử có trọng số rủi ro), nguyên thủy chỉnh sửa nguyên tử, v.v. Đối thủ gần nhất (code-review-graph) có 22 công cụ; những công cụ khác có 5-9.

Hỗ trợ tác nhân rộng nhất

Hơn một chục tích hợp tác nhân mã hóa AI với định dạng cấu hình gốc theo từng tác nhân. Không công cụ nào khác bao phủ nhiều tác nhân với tích hợp sâu như vậy. Claude Code nhận được hooks, quy tắc nhắc nhở và quyền công cụ được phép tự động. Kiro nhận được cấu hình MCP toàn cục, điều hướng tokensave.md được tải dưới dạng tài nguyên, một tác nhân được quản lý với phê duyệt công cụ tích hợp/tokensave cho phép, và hooks cho các rào cản ủy quyền cộng với đồng bộ sau ghi. Các tác nhân khác nhận được đăng ký máy chủ MCP trong định dạng cấu hình gốc của chúng.

Lập chỉ mục đa nhánh

Công cụ duy nhất trong lĩnh vực này có cơ sở dữ liệu đồ thị theo nhánh tùy chọn và diff/tìm kiếm chéo nhánh. Khi được bật, chuyển nhánh là tức thì -- không cần lập chỉ mục lại.

Theo dõi token mỗi lần gọi

Công cụ duy nhất báo cáo chính xác mỗi lần gọi công cụ MCP tiết kiệm bao nhiêu token, cộng với màn hình TUI trực tiếp trên tất cả các dự án và bộ đếm vòng đời.

Mã nguồn mở hoàn toàn

Rust được cấp phép MIT, có thể kiểm toán từ đầu đến cuối. Công cụ lõi của Dual-Graph (graperoot trên PyPI) là độc quyền -- bạn không thể thấy nó làm gì với đồ thị mã của bạn. OpenWolf là AGPL-3.0, yêu cầu các tác phẩm phái sinh phải được mã nguồn mở.

Hiệu suất

Điểm chuẩn chỉ mục đầy đủ trên cơ sở mã hỗn hợp Rust/Java/Scala gồm 1.782 tệp (57K nút, 103K cạnh):

Xử lý sự cố

"tokensave chưa được khởi tạo"

Thư mục .tokensave/ không tồn tại trong dự án của bạn.

tokensave init

Máy chủ MCP không kết nối

Tác nhân AI không thấy các công cụ tokensave.

1. Đảm bảo cấu hình tác nhân bao gồm máy chủ MCP tokensave (chạy tokensave doctor)
2. Khởi động lại tác nhân hoàn toàn
3. Kiểm tra rằng tokensave nằm trong PATH của bạn: which tokensave

Thiếu ký hiệu trong tìm kiếm

• Chạy tokensave sync để cập nhật chỉ mục
• Kiểm tra ngôn ngữ được hỗ trợ (xem bảng trên)
• Xác minh tệp không bị loại trừ bởi .gitignore

Lập chỉ mục chậm

Các dự án lớn mất nhiều thời gian hơn cho lần chỉ mục đầy đủ đầu tiên.

• Các lần chạy sau sử dụng đồng bộ gia tăng và nhanh hơn nhiều
• Sử dụng tokensave sync (không phải --force) cho các cập nhật hàng ngày
• Độ cũ được kiểm tra tự động trên mỗi lần gọi công cụ MCP khi tác nhân được kết nối

Vô hiệu hóa tokensave cho các dự án cụ thể

Nếu một dự án quá lớn và tokensave sử dụng quá nhiều RAM, bạn có thể vô hiệu hóa máy chủ MCP theo từng dự án bằng cách đặt TOKENSAVE_DISABLE_SERVER=true trong môi trường của nó. Máy chủ thoát sạch mà không khởi tạo.

Claude Code — thêm vào .claude/settings.json của dự án bạn:

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

Các tác nhân khác — đặt biến môi trường trong bất kỳ cấu hình nào tác nhân của bạn sử dụng để khởi chạy máy chủ MCP.

Bạn cũng có thể đặt nó toàn cục qua shell (TOKENSAVE_DISABLE_SERVER=true claude), nhưng điều này vô hiệu hóa máy chủ MCP tokensave cho mọi dự án trong phiên.

DISABLE_TOKENSAVE=true vẫn được hỗ trợ như một bí danh tương thích không dùng nữa cho các cấu hình được tạo trước khi biến này được đặt tên theo không gian tên.

Nguồn gốc

Dự án này là bản chuyển Rust của bản triển khai TypeScript CodeGraph gốc bởi @colbymchenry. Bản chuyển duy trì cùng kiến trúc và giao diện công cụ MCP trong khi tận dụng Rust cho hiệu suất và các ràng buộc tree-sitter gốc.

Xây dựng

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

Lịch sử Sao

Nhà tài trợ

Ký mã miễn phí trên Windows được cung cấp bởi SignPath.io, chứng chỉ bởi SignPath Foundation

Giấy phép

Giấy phép MIT -- xem LICENSE để biết chi tiết.

tokensave.dev