tokensave

Trí tuệ Mã nguồn Ngữ nghĩa cho Tác nhân Lập trình AI

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

Tại sao nên dùng tokensave?

Các tác nhân lập trình AI lãng phí token khi khám phá cơ sở mã. Mỗi lệnh grep, glob và đọc tệp đều tốn kém. Với các tác vụ phức tạp, tác nhân tạo ra nhiều tác nhân phụ Khám phá quét hàng trăm tệp chỉ để xây dựng ngữ cảnh.

tokensave cung cấp cho 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 phù hợp, mối quan hệ của chúng và mã nguồn, chỉ trong một lần gọi.

Cách thức 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: Tác nhân sử dụng grep, glob và Read để quét tệp -- nhiều lệnh gọi API, mức sử dụng token cao.

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

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 opencode        # OpenCode
tokensave install --agent pi              # Pi (pi.dev)
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)

Mỗi tác nhân được đăng ký máy chủ MCP của nó ở định dạng cấu hình gốc. Claude Code còn được thêm một hook PreToolUse (chặn các tác nhân Khám phá lãng phí), một hook UserPromptSubmit, một hook Stop, các quy tắc prompt trong CLAUDE.md và các quyền công cụ được tự động cho phép. Kiro nhận cấu hình MCP toàn cục, tokensave.md steering được tải dưới dạng tài nguyên và một 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 cho phép, 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.

Mọi thay đổi đều là 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ị cài đặt hook git post-commit và post-checkout toàn cục.

Cài đặt cục bộ cho 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). Để chỉ đăng ký tokensave cho dự án hiện tại, thêm --local:

tokensave install --local --agent claude

Điều này ghi cấu hình phạm vi dự án mà bạn có thể commit và chia sẻ với nhóm của mình. Đối với Claude, đó là ./.mcp.json, ./.claude/settings.json và ./CLAUDE.md. Các tác nhân được hỗ trợ: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie (mỗi tác nhân ghi tệp dự án riêng của nó, 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). 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 bằng tokensave uninstall --local.

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

cd /path/to/your/project
tokensave init

Lệnh này tạo một 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 repo bạn không 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ịu được Sự cố

Ngữ pháp Tree-sitter là mã C/C++ đã biên dịch. Đôi khi chúng gặp phải một xác nhận nội bộ hoặc kết thúc tiến trình bằng các đường dẫn mà việc xử lý panic của Rust không thể chặn được. Kể từ phiên bản 4.3.0, mọi tệp được phân tích cú pháp bên trong một tiến trình con worker tồn tại ngắn: nếu một ngữ pháp gây segfault, gọi abort() hoặc gặp tràn ngăn xếp, chỉ worker đó chết. Nhóm worker tạo lại nó, tệp vi phạm được ghi nhật ký và bỏ qua, và sync tiếp tục chạy.

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

Các nguyên thủy chỉnh sửa (tokensave_str_replace, tokensave_insert_at, v.v.) vẫn chạy trong tiến trình chính: chúng nhắm mục tiêu một tệp tại một thời điểm mà chi phí tiến trình con sẽ chiếm ưu thế, và một sự cố trích xuất ở đó sẽ hiển thị ngay lập tức 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 biệt cho mỗi nhánh git. Khi được bật, việc chuyển nhánh không bao giờ cho bạn 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 một nhánh khác. Theo dõi đa nhánh là tùy chọn tham gia -- 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 thức 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à chỉ đồng bộ các tệp khác biệt. Điều này có nghĩa là việc 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 xuyên nhánh

Ba công cụ MCP cho phép truy vấn xuyên nhánh mà không cần chuyển checkout 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). 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 DB, 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ừ DB của nhánh tổ tiên gần nhất và bao gồm một cảnh báo trong mỗi phản hồi công cụ đề nghị 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 lệnh 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ề DB tổ tiên. Hai cơ chế độc lập đảm nhiệm việc này; các dự án ở chế độ DB đơn không bao giờ bị ảnh hưởng và không cơ chế nào từng chạm vào cơ sở dữ liệu của nhánh mặc định.

Hook Git (khi checkout nhánh). Hook post-checkout mà tokensave install thiết lập nhận ra một lần checkout nhánh (trái ngược với checkout tệp) và chạy tokensave branch add trong nền. Lệnh đó là no-op 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 kém gì.

Tự động theo dõi khi mở (tùy chọn tham gia). 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 nó trong 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, ghi đè cấu hình cho mỗi lần chạy (bất kỳ giá trị nào cũng bật nó ngoại trừ 0, false, no, off hoặc để trống). Việc sao chép là cùng một bản sao DB tổ tiên gần như tức thì mà một 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ến hành với dự phòng tổ tiên thông thường, vì vậy nó không bao giờ có thể 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 sẽ minh bạch cung cấp cho nó đồ thị riêng cho mỗi nhánh; với auto_track được bật, ngay cả một nhánh được tạo bên ngoài checkout (ví dụ: trong một worktree mới) cũng được phát hiệ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 giữ các quyết định và ngữ cảnh vùng mã nguồn qua các phiên làm việc, được lưu trữ trong .tokensave/tokensave.db của 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 qua từng phiên làm việc.

Sổ cái tiết kiệm

Mỗi lần gọi MCP đều ghi một dòng chỉ-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, được làm mới hàng ngày qua LiteLLM).

Điểm chuẩn có thể tái tạo

tokensave bench chạy một tập 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 bộ tệp (phản ánh phương pháp luận CCE):

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

Đo lường trên repo này (chính tokensave) sử dụng tập truy vấn chung đi kèm:

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

Tập truy vấn mặc định nhắm đến các mẫu có trong hầu hết các cơ sở mã ứ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 các con số 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.

Điểm chuẩn tiêu chí trên các repo thực tế lớn

benches/large_repos.rs là một điểm chuẩn vi mô criterion thực thi các công cụ MCP từ đầu đến cuối trên bốn cơ sở mã nguồn mở lớn được ghim tại các tham chiếu 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, do đó thời gian có thể tái tạo qua các lần chạy.

Các repo và tham chiếu được ghim (được định nghĩa trong benches/repos.rs):

Mỗi repo được sao chép nông (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) trong lần sử dụng đầu tiên và được lưu vào bộ nhớ đệm cục bộ; các lần chạy sau tái sử dụng bản sao đã kiểm xuất. Đầu ra Git được truyền trực tiếp đến terminal để quá trình tải về nhiều GB hiển thị tiến trình thời gian thực.

Các công cụ được bao phủ (mỗi công cụ 5 truy vấn). 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 đang PATH) ast_grep_rewrite.

Đồng bộ cưỡng bức mỗi lần chạy. Trước khi bất kỳ điểm chuẩn nào được kích hoạt, bộ khai thác 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.

Điểm chuẩn ghi và dọn dẹp. Các 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ộ khai thác sử dụng iter_batched của criterion — một tệp tạm nhỏ dưới <repo>/.tokensave-bench-scratch/ được viết lại với nội dung đã biết trước mỗi lần lặp được tính thời gian, sau đó công cụ chỉnh sửa chạy trên đó. Sau khi tất cả các điểm chuẩn kết thúc, bộ khai thác 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ề tham chiếu được ghim.

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

Chạy nó:

# Required: a writable cache directory for the cloned repos + their indexes.
# 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 chưa được đặt, điểm chuẩn sẽ in một thông báo và đăng ký không điểm chuẩn nào (vì vậy cargo bench --all vẫn nhẹ trên máy của người đóng góp).

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

Lọc điểm chuẩn 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 các tham chiếu được ghim (ví dụ: sang bản phát hành mới hơn hoặc SHA cụ thể), chỉnh sửa REPOS trong benches/repos.rs và xóa điểm đánh dấu $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 dọn dẹp sau khi chạy (ví dụ: bạn Ctrl-C giữa chừng điểm chuẩn), chạy git stash --include-untracked && git stash drop bên trong mỗi thư mục repo sẽ khôi phục nó một cách thủ công.

Đầu dò ma trận kiểm thử MCP (scripts/mcp_probe)

scripts/mcp_probe/ là một bộ khai thác Python điều khiển tokensave serve qua stdio trên một tập hợp các repo thực tế có thể cấu hình và thực thi 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 cho mỗi công cụ / mỗi repo. Cùng một bộ khai thác 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 báo lỗi, hết thời gian chờ, hoặc trả về kết quả trống sẽ nổi bật như một 🚩.
• Đầu dò hiệu năng. Thời gian mỗi lần gọi được ghi lại trong TSV; cùng một kho repo cố định cũng đóng vai trò như một so sánh thô giữa các phiên bản. Lỗi chu kỳ tokensave_inheritance_depth hiện tại đã được tìm thấy bởi bộ khai thác này khi một công cụ duy nhất trên polkadot-sdk hết thời gian chờ ở mức >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 tiếp theo), 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 (thoát khỏi hàng đợi máy chủ), build_matrix.py đọc TSV và phát ra markdown, các mô-đun tools/<lang>.py đóng góp các tập truy vấn cho mỗi ngôn ngữ (Rust đi kèm; 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 chờ), ∅ E/N (trống), 🐢 ok/slow (các lần gọi >10 giây). Bất kỳ ô nào mang lỗi hoặc hết thời gian chờ đều nhận được một 🚩 ở 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 nằm trong nhật ký TSV để theo dõi.

Khác với điểm chuẩn 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 tham chiếu được ghim và tạo ra các báo cáo thống kê dưới target/criterion/; mcp_probe thực thi mọi công cụ với một tập truy vấn rộng hơn trên bất kỳ repo nào bạn trỏ đến, tối ưu hóa cho độ bao phủ rộng thay vì độ chính xác đo lường.

Hơn 80 Công cụ MCP

Máy chủ phơi bày hơn 80 công cụ (ít hơn một khi tệp nhị phân ast-grep tùy chọn không có trên PATH); các bảng dưới đây 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 với readOnlyHint. Các nguyên thủy chỉnh sửa được giới hạn trong các tệp đơn lẻ và lập chỉ mục lại tại chỗ; các công cụ đường cơ sở phiên và ghi nhớ bộ 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.

Khám phá

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

Chất lượng Mã

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

Năm công cụ bề mặt các 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 nhân trên các chiều độc lập để không chiều nào có thể bị lợi dụng.

Phiên làm việc

Chụp nhanh các số liệu sức khỏe khi bắt đầu một phiên lập trình AI, sau đó so sánh vào cuối để xem những gì đã cải thiện hoặc thoái lui.

Các Hàm Nguyên Thủy Chỉnh Sửa

Bốn công cụ ghi cho phép agent sửa file mà không gặp rủi ro về regex hay shell-quoting. Mỗi công cụ là đơn file, có neo, và kích hoạt tái lập chỉ mục 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 Mã Nguồn

Đ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ạng JSON
• tokensave://files -- cây file đã 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 ký hiệu
• 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 số token nó tiết kiệm được 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ị có bao nhiêu token file thô đã được tránh bởi lần gọi cụ thể đó.

Khả năng 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 vào 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 để truy vấn tổng hợp nhanh. Giá được làm mới từ LiteLLM mỗi 24 giờ và quay lại 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 tiết kiệm / tổng token). TUI tokensave monitor hiển thị bảng chi phí trực tiếp cùng với nguồn cấp dữ liệu 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 lai một dòng ra terminal.

Các danh mục phân loại tác vụ: Lập trình, Gỡ lỗi, Phát triển tính năng, Tái cấu trúc, Kiểm thử, Khám phá, Lập kế hoạch, Ủy quyền, Thao tác Git, Xây dựng/Triển khai, Động não, Hội thoại, Chung. 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 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ục hiển thị các lần gọi công cụ MCP từ tất cả dự án trong thời gian thực, thông qua bộ đệm vòng ánh xạ bộ nhớ dùng chung tại ~/.tokensave/monitor.mmap. Mỗi mục hiển thị tên dự án, tên công cụ, và chênh lệch token. Bảng chi phí ở trên cùng hiển thị chi tiêu hôm nay, tiết kiệm, hiệu quả, và mô hình hàng đầu (được làm mới mỗi 30 giây).

Bộ đếm phiên và trọn đờ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ê chỉ mục 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 trọn đời của dự án và toàn cầu:

Bộ đếm toàn cầu

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 cầu. Việc tải lên chỉ gửi một số duy nhất (ví dụ: 4823) không có thông tin nhận dạng. Từ chối bằng tokensave disable-upload-counter.

Độ Mới Của Chỉ Mục

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

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

Đồng bộ 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 đồng bộ bắt kịp không chặn để nhận bất kỳ thay đổi nào được thực hiện khi không có agent nào được đính kèm — một git pull, một chỉnh sửa IDE, một bước xây dựng — để lần gọi công cụ đầu tiên của phiên thấy một chỉ mục mới.

Công việc đa agent và git worktree. Khi nhiều agent làm việc đồng thời trên cùng một dự án, giả định mạnh mẽ là mỗi agent hoạt động trong git worktree riêng của nó. Worktree là các bản sao hệ thống file độc lập của cùng một kho lưu trữ: agent A và agent B mỗi bên có bản sao riêng của mọi file, vì vậy chúng không bao giờ ghi đè lên 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 bản sao 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 một 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 khóa chéo agent trên một thư mục có thể thay đổi dùng chung.

Quy trình chỉ dùng CLI. Nếu bạn chạy các lệnh tokensave mà không có agent đính kèm (không có máy chủ MCP), việc kiểm tra lỗi thời không chạy giữa các lệnh. Cài đặt git hook để giữ chỉ mục tự động mới sau mỗi lần 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 tokensave daemon độc lập và tính năng tự khởi động launchd/systemd/Windows Service của nó đã bị loại bỏ trong 6.0.0. Trình theo dõi file cấp hệ điều hành nhúng thay thế daemon đã bị loại bỏ trong 6.1.0 (nó gây ra CPU và bộ nhớ tăng vọt trên các monorepo lớn với cây node_modules hoặc target sâu). Mô hình lỗi thời theo yêu cầu ở trên là thiết kế hiện tại.

Nếu bạn vẫn còn tự khởi động daemon từ 5.x, hãy gỡ bỏ 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 tệp nhị phân nền tảng chính xác từ các bản phát hành GitHub và thay thế tệp nhị phân đang chạy tại chỗ. Hỗ trợ các kênh ổn định và beta một cách độ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, tokensave thực hiện tự động vào lần khởi chạy tiếp theo — bạn không bao giờ phải chạy cài đặt lại hoặc lập chỉ mục lại bằng tay.

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

Buộc lập chỉ mục lại theo dự án (chỉ major). Bump major có nghĩa là các chỉ mục 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: vào lần gọi công cụ MCP đầu tiên trong một dự án sau khi nâng cấp major, nó sinh ra một lần lập chỉ mục lại toàn bộ 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ế tệp nhị phân bên ngoài tokensave upgrade — brew upgrade tokensave hoặc cargo install tokensave — được phát hiện theo cùng một 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 vào lần khởi chạy tiếp theo giống như sau khi 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ế đánh dấu, phiên bản lược đồ cơ sở dữ liệu độc lập, và các quy tắc bảo trì để cắt bản phát hành.

Tham Khảo 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                    # Start MCP server
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
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 cho cài đặt tokensave của bạn:

tokensave doctor

Kiểm tra: vị trí tệp nhị phân, chỉ mục dự án, DB toàn cục, cấu hình người dùng, tích hợp agent (máy chủ MCP, hook, quyền, quy tắc nhắc), và kết nối mạng. Nếu thiếu bất kỳ quyền công cụ nào sau khi 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 đặt sử dụng đúng lệnh con tokensave và tự động sửa chữa các hook bị hỏng.

Cách Nó Hoạt Động với Claude Code

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

Kết quả: Claude có được sự hiểu biết mã tương tự với ít token hơn nhiều. Một agent Khám phá điển hình đọc 20-50 file; tokensave trả về các ký hiệu, mối quan hệ và đoạn mã liên quan từ chỉ mục đượ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 (lập chỉ mục, 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 cầu gửi một yêu cầu HTTP POST duy nhất với nội dung JSON như {"amount": 4823}. Không có cookie, không theo dõi, không có ID người dùng. Cloudflare Worker ghi lại quốc gia từ địa chỉ IP của bạn (lấy từ tiêu đề yêu cầu) để 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) để cập nhật giá mô hình Claude cho tokensave cost. Không có dữ liệu nào được gửi đi -- đó là một yêu cầu HTTPS GET thuần túy. Phản hồi được lưu vào cache tại ~/.tokensave/pricing.json trong 24 giờ. Nếu việc tải thất bại, tokensave sử dụng bảng giá đã biên dịch sẵn.

Hơ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 cấp độ, điều khiển bởi cờ tính năng Cargo. Mỗi cấp độ bao gồm tất cả các ngôn ngữ từ cấp độ bên dưới nó. Tiêu đề Markdown được trích xuất thành các nút Module với các cạnh phân cấp Contains để 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. Tệp nhị phân 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 bộ trích xuất TypeScript, không phụ thuộc ngữ pháp bổ sung).

Medium (Lite + 9 ngôn ngữ khác) -- --features medium

Full (Medium + mọi thứ khác) -- mặc định

Các ngôn ngữ riêng lẻ cũng có thể được chọn lọc mà không cần toàn bộ cấp độ:

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ị lời 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 chéo tệp.

tokensave so với CodeGraph

tokensave là bản viết lại từ đầu bằng Rust của CodeGraph (Node.js/TypeScript). Cả hai đều xây dựng đồ thị mã ngữ nghĩa cho các tác nhân lập trình 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à một lựa chọn vững chắc nếu bạn 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 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 thay thế

Một số công cụ giảm mức sử dụng token cho các tác nhân lập trình AI. Đây là lý do tokensave nổi bậ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ôi trường 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 duy nhất ~25 MB với tất cả hơn 50 ngữ pháp tree-sitter đi kèm. 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, cấu trúc, trường, cạnh lời gọi, 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 những 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 cấu trúc này?" Hơn 80 công cụ MCP chuyên biệt của tokensave bao gồm duyệt đồ thị lời 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, 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ủ cạnh tranh 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 lập trình AI với định dạng cấu hình gốc cho mỗi tác nhân. Không có 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 hook, quy tắc nhắc và quyền công cụ tự động cho phép. Kiro nhận được cấu hình MCP toàn cục, tokensave.md steering đượ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à hook cho các rào chắ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 ở đị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 không gian này có cơ sở dữ liệu đồ thị tùy chọn cho mỗi nhánh và diff/tìm kiếm chéo nhánh. Khi được bật, việc 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ời gọi

Công cụ duy nhất báo cáo chính xác mỗi lời gọi công cụ MCP riêng lẻ đã tiết kiệm được 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 trọn đờ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ụ cốt 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ở mã nguồn.

Hiệu suất

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

Khắc phục sự cố

"tokensave not initialized"

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 hoàn toàn tác nhân
3. Kiểm tra xem tokensave có trong PATH của bạn không: 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 xem ngôn ngữ có được hỗ trợ không (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 lập chỉ mục đầy đủ đầu tiên.

• Các lần chạy sau sử dụng đồng bộ tăng dần 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 một agent đang 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 nó cho từng dự án bằng cách đặt DISABLE_TOKENSAVE=true trong môi trường máy chủ MCP. Máy chủ sẽ thoát một cách sạch sẽ mà không khởi tạo.

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

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

Các agent khác — đặt biến môi trường trong bất kỳ cấu hình nào mà agent 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 thông qua shell (DISABLE_TOKENSAVE=true claude), nhưng điều này vô hiệu hóa tokensave cho mọi dự án trong phiên làm việc.

Nguồn gốc

Dự án này là một bản port Rust của bản triển khai TypeScript gốc CodeGraph bởi @colbymchenry. Bản port duy trì cùng kiến trúc và giao diện công cụ MCP trong khi tận dụng Rust để có hiệu suất và các liên kết 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