tokensave

Kecerdasan Kode Semantik untuk Agen Coding AI

Lebih sedikit token • Lebih sedikit pemanggilan alat • 100% lokal

Mengapa tokensave?

Agen coding AI membuang token untuk menjelajahi basis kode. Setiap grep, glob, dan pembacaan file memakan biaya. Pada tugas kompleks, agen memunculkan beberapa sub-agen Explore yang memindai ratusan file hanya untuk membangun konteks.

tokensave memberi agen graf pengetahuan semantik yang sudah terindeks. Alih-alih memindai file, agen melakukan kueri ke graf dan langsung mendapatkan jawaban terstruktur -- simbol yang tepat, relasinya, dan kode sumbernya, dalam satu pemanggilan.

Cara Kerjanya

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

Tanpa tokensave: Agen menggunakan grep, glob, dan Read untuk memindai file -- banyak pemanggilan API, penggunaan token tinggi.

Dengan tokensave: Agen melakukan kueri ke graf melalui alat MCP -- hasil instan, pemrosesan lokal, lebih sedikit token.

Fitur Utama

Mulai Cepat

1. Instalasi

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 (platform apa pun):

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

Biner siap pakai (Linux, Windows, macOS):

Unduh dari rilis terbaru dan letakkan biner di PATH Anda.

2. Konfigurasikan agen Anda

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

Setiap agen mendapatkan server MCP-nya terdaftar dalam format konfigurasi native. Claude Code juga mendapatkan hook PreToolUse (memblokir agen Explore yang boros), hook UserPromptSubmit, hook Stop, aturan prompt di CLAUDE.md, dan izin alat yang diizinkan otomatis. Kiro mendapatkan konfigurasi MCP global, tokensave.md steering yang dimuat sebagai resource, dan agen default yang dikelola tokensave dengan persetujuan alat bawaan/tokensave yang permisif, hook guardrail delegasi, dan sinkronisasi pasca-penulisan; agen Kiro yang dikelola pengguna dipertahankan.

Instalasi OMP global menargetkan profil yang dilaporkan oleh omp config path polos, menulis <resolved-agent-dir>/mcp.json dan <resolved-agent-dir>/rules/tokensave.md. Ekspor OMP_PROFILE atau PI_PROFILE yang kompatibel dengan OMP saat menginstal ke profil bernama; resolver OMP juga menghormati PI_CONFIG_DIR dan PI_CODING_AGENT_DIR. Tokensave mempercayai resolver native tersebut alih-alih menduplikasi logika profil OMP. Tokensave menginstal MCP dan aturan advisory untuk OMP; ia tidak menginstal penegakan hook OMP.

Semua perubahan bersifat idempoten -- aman dijalankan lagi setelah peningkatan. Setelah penyiapan agen, Anda akan ditawari hook git global post-commit dan post-checkout. tokensave uninstall menghapus hook tersebut bersama integrasi agen; berikan --keep-git-hooks untuk membiarkannya, atau kelola sendiri dengan tokensave githooks.

Instalasi untuk beberapa agen sekaligus

Ulangi --agent untuk menginstal beberapa agen dalam satu kali jalan. Pemberian izin, penawaran hook git, dan penulisan konfigurasi global masing-masing terjadi sekali, berapa pun jumlah agen yang Anda daftarkan:

tokensave install --agent claude --agent cursor --agent droid

Instalasi lokal proyek

Secara default tokensave install mendaftarkan server MCP di konfigurasi agen global Anda (mis. ~/.claude.json). Untuk mendaftarkan tokensave hanya untuk proyek saat ini, tambahkan --local:

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

Ini menulis konfigurasi berlingkup proyek yang dapat Anda commit dan bagikan dengan tim Anda. Untuk Claude itu adalah ./.mcp.json, ./.claude/settings.json, dan ./CLAUDE.md; OMP menggunakan ./.omp/mcp.json dan ./.omp/rules/tokensave.md tanpa memanggil CLI OMP. Agen yang didukung: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank, pi (masing-masing menulis file proyeknya sendiri, mis. .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 untuk plank, .pi/mcp.json dan ./AGENTS.md untuk pi). Agen lain tidak memiliki konfigurasi berlingkup proyek dan melaporkan kesalahan dengan --local.

Hapus instalasi lokal proyek dengan tokensave uninstall --local.

3. Indeks proyek Anda

cd /path/to/your/project
tokensave init

Ini membuat direktori .tokensave/ dengan basis data graf pengetahuan. Inisialisasi dan sinkronisasi adalah perintah terpisah: init adalah opt-in satu kali per proyek, sedangkan sync hanya memperbarui proyek yang sudah diinisialisasi. Ini mencegah hook git global diam-diam membuat basis data di repo yang tidak pernah Anda maksudkan untuk diindeks. Setelah init, gunakan tokensave sync untuk memperbarui secara inkremental -- hanya file yang berubah yang diindeks ulang.

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

Sinkronisasi Tahan Crash

Grammar tree-sitter adalah kode C/C++ yang dikompilasi. Kadang-kadang mereka memicu assertion internal atau mengakhiri proses melalui jalur yang tidak dapat dicegat penanganan panic Rust. Sejak v4.3.0, setiap file di-parse di dalam subproses worker berumur pendek: jika grammar segfault, memanggil abort(), atau mengalami stack overflow, hanya worker yang mati. Pool memunculkannya kembali, file yang bermasalah dicatat dan dilewati, dan sync terus berjalan.

Worker adalah subperintah extract-worker tersembunyi yang diautentikasi terhadap induk melalui token 256-bit per-spawn, yang diperlukan baik sebagai variabel env TOKENSAVE_WORKER_TOKEN maupun sebagai 32 byte pertama yang diterima di stdin. Pemanggilan langsung oleh pengguna akan gagal. Konkurensi worker mengikuti cpu_usage di .tokensave/config.json: low menggunakan satu worker, balanced (default) menggunakan setengah CPU yang tersedia dibulatkan ke atas, dan performance menggunakan semua CPU yang tersedia. tokensave init pertama di sebuah mesin melakukan benchmark sekali dan menyimpan profil yang direkomendasikan di ~/.tokensave/benchmark.toml, yang digunakan ulang oleh setiap proyek yang tidak memiliki cpu_usage sendiri; tokensave config benchmark [--force|--show|--reset] mengelola hasil tersebut, dan TOKENSAVE_CPU_USAGE atau cpu_usage global di ~/.tokensave/config.toml menimpanya (lihat panduan pengguna). memory_usage secara independen membatasi parser ekstraksi simultan: low menggunakan satu, balanced (default) paling banyak dua, dan performance mempertahankan batas CPU. Pemeriksaan preflight otomatis dapat menurunkan lebih lanjut konkurensi parser ketika ruang RAM fisik terbatas, termasuk dalam mode performance. Ini mengurangi memori parser dengan kemungkinan biaya throughput; total memori graf tetap proporsional terhadap proyek, jadi ini bukan batas RAM keras. TOKENSAVE_WORKERS dapat menurunkan batas subproses lebih lanjut. Batas-batas ini bukan batas persentase CPU. Mulai ulang server MCP setelah mengubah profil; pilih keluar dari isolasi subproses dengan TOKENSAVE_DISABLE_SUBPROCESS=1.

Primitif edit (tokensave_str_replace, tokensave_insert_at, dll.) tetap berjalan dalam proses: mereka menargetkan satu file pada satu waktu di mana overhead subproses akan mendominasi, dan crash extractor di sana langsung terlihat oleh agen.

Pengindeksan Multi-Cabang (Opsional)

tokensave dapat secara opsional memelihara grafik kode terpisah per cabang git. Saat diaktifkan, berpindah cabang tidak pernah memberi Anda hasil yang basi dan tidak pernah mengindeks ulang file yang sudah Anda parsing di cabang lain. Pelacakan multi-cabang bersifat opt-in -- tanpanya, tokensave menggunakan satu basis data untuk semua cabang.

Cara kerjanya

Saat Anda melacak sebuah cabang, tokensave menyalin DB leluhur terdekat dan hanya menyinkronkan file yang berbeda. Artinya, melacak cabang fitur dari main hampir instan -- ia hanya mem-parsing file yang Anda ubah.

Perintah 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

Alat MCP lintas cabang

Tiga alat MCP memungkinkan kueri lintas cabang tanpa berpindah checkout:

• tokensave_branch_search -- cari simbol di grafik cabang lain
• tokensave_branch_diff -- bandingkan grafik kode antara dua cabang: simbol yang ditambahkan, dihapus, dan diubah (tanda tangan berbeda). Mendukung filter file dan kind.
• tokensave_branch_list -- daftar cabang yang dilacak beserta ukuran DB, cabang induk, dan waktu sinkronisasi

Fallback cabang

Saat server MCP tidak dapat menemukan basis data untuk cabang saat ini, ia menyajikan dari DB cabang leluhur terdekat dan menyertakan peringatan di setiap respons alat yang menyarankan Anda menjalankan tokensave branch add.

Pelacakan cabang otomatis (v7.3.0)

Setelah mode multi-cabang di-bootstrap (sebuah tokensave branch add manual pertama membuat metadata cabang), cabang baru dapat dilacak secara otomatis alih-alih fallback ke DB leluhur. Dua mekanisme independen mencakup hal ini; proyek dalam mode DB tunggal tidak pernah terpengaruh, dan tidak ada mekanisme yang menyentuh basis data cabang default.

Hook Git (saat checkout cabang). Hook post-checkout yang disiapkan oleh tokensave install mengenali checkout cabang (berbeda dengan checkout file) dan menjalankan tokensave branch add di latar belakang. Perintah itu adalah no-op ketika cabang sudah dilacak atau merupakan cabang default, sehingga berpindah biasa antara cabang yang dikenal tidak memakan biaya apa pun. Checkout awal dari git clone yang baru dan dari git worktree add baru juga merupakan checkout cabang, dan bisa mendarat di cabang yang bukan cabang default (git clone -b feature, git worktree add -b feature); di sana hook menjalankan tokensave init terlebih dahulu dan tokensave branch add setelahnya, dalam urutan itu. Hook yang ditulis oleh versi sebelumnya mempertahankan isi yang dipasang bersamanya — penginstal tidak pernah menulis ulang hook yang sudah ada — jadi pada instalasi tersebut worktree baru masih memerlukan auto_track di bawah, atau tokensave branch add manual.

Pelacakan otomatis saat buka (opt-in). Saat TokenSave::open berjalan — perintah CLI atau mulai server MCP — dan cabang aktif belum dilacak, tokensave dapat melacaknya saat itu juga dengan menyalin DB leluhur terlacak terdekat dan mencatatnya di metadata cabang. Ini dikendalikan oleh bidang konfigurasi auto_track (default false) atau variabel lingkungan TOKENSAVE_AUTO_TRACK, yang menimpa konfigurasi per-run (nilai apa pun mengaktifkannya kecuali 0, false, no, off, atau kosong). Salinan tersebut adalah salinan DB leluhur yang hampir instan sama seperti yang dilakukan branch add manual; tidak ada sinkronisasi yang berjalan saat itu — hook post-commit menjaga DB cabang baru tetap segar saat Anda commit, atau jalankan tokensave sync untuk menyegarkan segera. Pelacakan otomatis bersifat strictly best-effort: kegagalan apa pun dilaporkan sebagai peringatan dan open() melanjutkan dengan fallback leluhur yang biasa, sehingga tidak pernah dapat merusak pemanggilan alat.

Pembersihan otomatis (opt-in). Setel "auto_gc": true di .tokensave/config.json (atau TOKENSAVE_AUTO_GC=1 untuk satu kali jalan) untuk mengumpulkan indeks yang cabang Git lokalnya telah dihapus. Pembersihan berjalan saat proyek dibuka dan selama pemeriksaan kesegaran normal server MCP. Ia menggunakan kolektor yang sama dengan tokensave branch gc, mempertahankan cabang default, cabang yang ada, cabang yang digunakan oleh worktree Git mana pun, dan basis data yang disajikan oleh server TokenSave yang sedang berjalan. Kueri Git yang gagal atau kunci sinkronisasi yang sibuk melewati pembersihan otomatis tanpa menggagalkan perintah. Nilai default adalah false, sehingga proyek lama mempertahankan indeksnya hingga secara eksplisit dibersihkan. TOKENSAVE_AUTO_GC=0 menimpa pengaturan proyek yang diaktifkan; tokensave branch gc eksplisit berjalan terlepas dari pengaturan ini.

Singkatnya: dengan hook terpasang, melakukan checkout cabang fitur baru — termasuk cabang tempat clone atau worktree baru dimulai — secara transparan memberinya grafik per-cabangnya sendiri; dengan auto_track diaktifkan, bahkan cabang yang dibuat di luar checkout akan diambil saat pertama kali tokensave membuka proyek di cabang tersebut.

Lihat docs/BRANCHING-USER-GUIDE.md untuk panduan lengkapnya.

Memori Lintas Sesi

Tiga alat MCP menyimpan keputusan dan konteks area kode lintas sesi, disimpan dalam .tokensave/tokensave.db per-proyek.

Gunakan ini agar agen tidak perlu menjelaskan ulang pilihan arsitektur dari sesi ke sesi.

Buku Besar Penghematan

Setiap panggilan MCP menulis baris append-only ke ~/.tokensave/global.db (tabel savings_ledger). Periksa dengan tokensave gain:

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

Estimasi dolar menggunakan modul harga yang ada (harga input Sonnet, disegarkan setiap hari melalui LiteLLM).

Tolok Ukur yang Dapat Direproduksi

tokensave bench menjalankan kumpulan kueri tetap melalui tokensave_context dan melaporkan penghematan pengambilan vs baseline file penuh (mencerminkan metodologi CCE):

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

Diukur terhadap repo ini (tokensave itu sendiri) menggunakan kumpulan kueri generik yang disertakan:

Agregat: penghematan pengambilan rata-rata 88% (142,8k → 5,5k token di 10 kueri).

Kumpulan kueri default menargetkan pola yang ada di sebagian besar basis kode aplikasi (CLI, daemon, layanan). Jalankan pada proyek Anda sendiri dengan tokensave bench untuk melihat angka Anda, atau tulis file kueri yang disesuaikan (--queries my.toml) untuk recall yang lebih ketat.

Bench criterion terhadap repo dunia nyata yang besar

benches/large_repos.rs adalah mikro-benchmark criterion yang menjalankan alat MCP secara end-to-end terhadap empat basis kode open-source besar yang dipatok pada ref konstan. Setiap alat digerakkan oleh setidaknya 5 kueri dengan argumen (id node, nama berkualifikasi, glob file, …) yang diambil sampelnya dari grafik terindeks sekali per repo, sehingga waktu dapat direproduksi lintas run.

Repo dan ref yang dipatok (didefinisikan di benches/repos.rs):

Setiap repo di-clone secara shallow (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) pada penggunaan pertama dan di-cache secara lokal; run berikutnya menggunakan kembali checkout tersebut. Output Git dialirkan ke terminal sehingga pengambilan multi-GB menampilkan progres secara real-time.

Alat yang dicakup (5 kueri masing-masing). Alat baca — 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. Alat tulis — str_replace, multi_str_replace, insert_at, dan (jika ast-grep aktif di PATH) ast_grep_rewrite.

Force-sync pada setiap run. Sebelum benchmark apa pun dijalankan, harness menjalankan yang setara dengan tokensave sync --force pada setiap repo (index_all() terlepas dari kesegaran .tokensave/) sehingga waktu selalu mencerminkan sumber yang dipatok.

Bench tulis dan pembersihan. Alat tulis memutasi file. Untuk menjaga prasyarat "kecocokan harus unik" tetap terpenuhi, harness menggunakan iter_batched milik criterion — file scratch kecil di bawah <repo>/.tokensave-bench-scratch/ ditulis ulang dengan konten yang diketahui sebelum setiap iterasi yang diukur, lalu alat edit dijalankan terhadapnya. Setelah semua benchmark selesai, harness menjalankan git stash --include-untracked && git stash drop di dalam setiap repo yang telah disiapkan sehingga working tree kembali ke ref yang dipatok.

Konfigurasi criterion. Bench menimpa default criterion menjadi sample_size = 10 dan measurement_time = 30s (vs standar 100 / 5d), yang memberi setiap pengukuran per-kueri ~30 detik pengukuran — cukup sehingga alat lambat seperti tokensave_context pada polkadot-sdk menghasilkan angka yang stabil.

Jalankan:

# 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

Jika TOKENSAVE_BENCH_REPOS_DIR tidak disetel, bench mencetak pemberitahuan dan mendaftarkan nol benchmark (sehingga cargo bench --all tetap murah di mesin kontributor).

Konfigurasi (semua opsional, melalui lingkungan):

Memfilter benchmark menggunakan CLI criterion standar — misalnya, hanya alat search pada scipy:

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

Laporan (HTML + sampel mentah) tersimpan di bawah target/criterion/.

Untuk mengubah ref yang dipatok (mis. ke rilis yang lebih baru atau SHA tertentu), edit REPOS di benches/repos.rs dan hapus penanda $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref yang sesuai agar run berikutnya mengambil ulang. Jika Anda melewati pembersihan pasca-run (mis. Anda Ctrl-C di tengah bench), menjalankan git stash --include-untracked && git stash drop di dalam setiap direktori repo memulihkannya secara manual.

Probe matriks uji MCP (scripts/mcp_probe)

scripts/mcp_probe/ adalah harness Python yang menjalankan tokensave serve melalui stdio terhadap sekumpulan repo nyata yang dapat dikonfigurasi dan menjalankan setiap alat MCP read-only dengan 5 varian kueri per bahasa, menghasilkan tabel status per-alat / per-repo. Harness yang sama melayani dua tujuan:

• Sweep regresi. Dukungan bahasa baru, alat baru, atau refactor — jalankan ulang matriks dan sel mana pun yang baru error, timeout, atau mengembalikan hasil kosong akan menonjol sebagai 🚩.
• Probe performa. Waktu per-panggilan dicatat dalam TSV; korpus repo tetap yang sama juga berfungsi sebagai perbandingan lintas versi yang kasar. Bug siklus tokensave_inheritance_depth saat ini ditemukan oleh harness ini ketika satu alat pada polkadot-sdk timeout pada >60 d. Tata Letak — probe.py adalah penggerak (JSON-RPC yang dicocokkan berdasarkan id sehingga alat yang lambat tidak dapat merusak panggilan berikutnya), isolated.py menjalankan ulang satu alat dengan server baru pada setiap panggilan (menghindari antrean server), build_matrix.py membaca TSV dan menghasilkan markdown, modul tools/<lang>.py menyumbangkan kumpulan kueri per bahasa (Rust sudah tersedia; tambahkan Python/Go/… dengan menambahkan modul baru), repos.toml mencantumkan repo target (timpa melalui $TOKENSAVE_PROBE_REPOS).

Jalankan cepat:

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

Sel keluaran adalah ✓ 5/5 (bersih), 🐛 e/N (galat), ⏱ N/N (timeout), ∅ E/N (kosong), 🐢 ok/slow (panggilan >10 dtk). Sel mana pun yang membawa galat atau timeout mendapat 🚩 di kolom paling kanan. Detail per panggilan dengan 100 karakter pertama dari setiap galat masuk ke log TSV untuk tindak lanjut.

Berbeda dari bench kriteria di atas: kriteria mengukur latensi per iterasi untuk kumpulan alat yang terfokus pada ref yang dipatok dan menghasilkan laporan statistik di bawah target/criterion/; mcp_probe menguji setiap alat dengan kumpulan kueri yang lebih luas pada repo mana pun yang Anda tunjuk, mengoptimalkan cakupan yang luas alih-alih presisi pengukuran.

80+ Alat MCP

Server mengekspos lebih dari 80 alat (berkurang satu ketika biner opsional ast-grep tidak ada di PATH). Sejak 7.14.0 hanya 11 alat inti plus tokensave_more yang dicantumkan secara default; sisanya dicantumkan sesuai permintaan melalui tokensave_more, tetap dapat dipanggil berdasarkan nama, dan semuanya dicantumkan dengan "tools": "full". Tabel di bawah mengelompokkan alat yang paling umum digunakan berdasarkan kategori. Sebagian besar bersifat hanya-baca, aman dipanggil secara paralel, dan dianotasi dengan readOnlyHint. Primitif edit dibatasi pada satu file dan mengindeks ulang di tempat; alat baseline sesi dan perekaman memori juga mengubah status .tokensave lokal dan dianotasi sebagai bukan hanya-baca. Tiga alat inti (tokensave_context, tokensave_search, tokensave_status) ditandai anthropic/alwaysLoad sehingga melewati perjalanan bolak-balik pencarian alat milik klien.

Kueri proyek lain yang sudah diinisialisasi

Alat baca semantik dapat mengueri graf lokal yang dipilih secara eksplisit tanpa memulai ulang server MCP:

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

Hasil yang dipilih menyertakan provenans root/cabang kanonis. ID node diberi namespace ke graf tersebut, dan selektor yang cocok harus diulang pada panggilan lanjutan. Misalnya, tindak lanjut untuk kueri yang dipilih berdasarkan cabang menyertakan kedua nilai:

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

graph_root harus berupa root absolut yang tepat dari proyek yang sudah diinisialisasi. graph_branch bersifat opsional dan, bila diberikan, harus menamai cabang yang dilacak. Pembukaan terpilih bersifat hanya-baca: tidak pernah menginisialisasi, menyinkronkan, memigrasi, melacak otomatis, atau menulis data graf/sumber. Pembukaan tersebut juga tidak berkontribusi pada akuntansi penghematan. Panggilan tanpa selektor berperilaku persis seperti sebelumnya.

graph_root hanya berguna jika Anda tahu proyek lain itu ada, jadi server memberi tahu Anda: proyek yang sudah diinisialisasi yang berada langsung di samping root yang dilayani disebutkan dalam instructions MCP, dalam tokensave_status, dan dalam hasil tokensave_search / tokensave_context yang kosong — titik di mana sebuah sesi jika tidak akan menyimpulkan bahwa suatu simbol tidak ada alih-alih melihat ke sebelah (#375). Hanya saudara langsung yang ditawarkan, paling banyak lima, dan tidak ada yang dibuka atau diindeks atas nama mereka; mengueri salah satunya tetap memerlukan graph_root eksplisit.

Selektor sengaja tidak tersedia pada alat yang menulis, menjalankan shell, atau bergantung pada checkout saat ini: primitif edit, alat VCS dan cabang, diagnostik dan eksekusi pengujian, introspeksi dependensi dan runtime, alat alur kerja dan memori sesi, alat cache persisten (tokensave_redundancy), dan administrasi server. Alat-alat tersebut menolak selektor alih-alih mengabaikannya secara diam-diam.

Penemuan

Ekstensi sumber kustom

Petakan ekstensi ke ekstraktor yang diaktifkan di .tokensave/config.json:

"language_aliases": { ".t": "perl", ".ep": "perl" }

Ini mengurai tes Perl lama tanpa mengganti namanya. Kunci menerima titik di depan yang opsional dan dicocokkan tanpa membedakan huruf besar/kecil; pemetaan yang tidak valid, bertentangan, tidak dikenal, atau dinonaktifkan akan menggagalkan sinkronisasi dengan galat konfigurasi. Alias menimpa asosiasi ekstensi bawaan dan pelacakan artefak. Gunakan project.json entries yang sudah ada dengan language untuk penimpaan file/glob, yang diprioritaskan di atas alias. Jalankan tokensave sync setelah mengedit pemetaan (sync -f juga berfungsi). Lihat panduan konfigurasi.

Artefak non-kode

tokensave_files mencakup lebih dari sekadar sumber. File yang ekstensinya tercantum dalam artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md, .bnd, .bndrun secara default) dilacak berdasarkan path sehingga pertanyaan seperti "di mana file .feature untuk alur login?" memiliki jawaban graf alih-alih find yang terblokir (#323). File tersebut tidak pernah diurai dan tidak menyumbangkan simbol; kind: "artifact" dan kind: "code" menyaring di antara keduanya, dan analisis yang berarti "kode" mengecualikannya. Ekstensi yang sudah ditangani oleh ekstraktor bahasa diabaikan dalam daftar ini, sehingga tidak dapat digunakan untuk menghentikan suatu bahasa diurai.

Daftar ini juga menentukan apa yang dapat dicari secara literal di dalamnya (#442). Pencarian literal (literal: true) atas tokensave_search membaca byte alih-alih simbol, sehingga tidak memerlukan parser -- tetapi ia mengiterasi file yang terindeks, sehingga hanya dapat menjangkau file yang memiliki baris di indeks. Dokumen .rst yang dilacak atau templat .tmpl tidak memiliki ekstraktor maupun entri artefak default, sehingga kecocokannya hilang; tambahkan ekstensinya di sini dan jalankan tokensave sync -f dan barisnya akan dicari seperti yang lain, dilaporkan dengan enclosing: null karena tidak ada konteks simbol. Respons literal yang tidak dapat menjangkau setiap file yang dilacak menyatakan hal itu dalam blok unscanned yang menyebutkan jumlah dan ekstensinya, sehingga jawaban parsial tidak pernah disajikan sebagai jawaban lengkap.

Graf Panggilan & Dampak

Kualitas Kode

Analitik Kesehatan Kode

Lima alat memunculkan sinyal kualitas struktural dari graf yang ada. Skor komposit menggunakan rata-rata geometrik atas dimensi independen sehingga tidak ada satu pun yang dapat dimanipulasi.

Sesi

Ambil snapshot metrik kesehatan di awal sesi pengkodean AI, lalu diff di akhir untuk melihat apa yang membaik atau memburuk.

Primitif Edit

Empat alat penulis yang memungkinkan agen mengubah file tanpa bahaya regex atau shell-quoting. Masing-masing bersifat satu-file, berjangkar, dan memicu pengindeksan ulang di tempat setelah menulis sehingga graf tidak pernah basi.

Git & Alur Kerja

Sistem Tipe

Porting

Multi-Cabang

Regresi kualitas cabang

Bandingkan dua indeks cabang yang sudah ada pada tip Git masing-masing:

tokensave quality-diff --base master --target feature/example
tokensave quality-diff --base master --target HEAD --json --fail-on regression
tokensave quality-diff --base origin/master --target feature/example --cyclomatic 15 --min-increase 5

Setiap referensi harus mengarah ke sebuah commit dan menamai cabang Tokensave yang dilacak. HEAD mengarah ke cabang simbolik saat ini; HEAD yang terlepas memerlukan cabang eksplisit. Nama refs/heads/... dan refs/remotes/... lengkap diterima. Buat dan sinkronkan setiap indeks secara eksplisit menggunakan alur kerja tokensave branch add / sync yang sudah ada sebelum membandingkan. Perbandingan tidak pernah melakukan checkout cabang atau membangun ulang indeks. Indeks yang hilang dan data analisis yang kosong merupakan error, termasuk perbandingan suatu cabang dengan dirinya sendiri.

Baseline adalah tip ke tip, bukan merge base. Pada cabang yang divergen, perbedaan yang dilaporkan dapat berasal dari salah satu cabang; ini bukan bukti bahwa suatu fitur memperkenalkan perbedaan tersebut sejak percabangan.

Diagnostik yang didukung menggunakan kembali data yang diekstrak/diindeks:

Ubah ambang dengan --cyclomatic, --cognitive, --function-lines, dan --fan-out (yang terakhir berlaku untuk fan-in dan fan-out). Masalah yang sudah ada di atas ambang menjadi worsened ketika metriknya meningkat setidaknya sebesar --min-increase (default 3); peningkatan yang lebih kecil tetap unchanged untuk gating. Melewati ambang adalah new; turun di bawahnya atau penghapusan adalah resolved; penurunan di atasnya adalah improved. Sisi siklik yang sudah ada sebelumnya tetap tidak berubah. Sisi yang sudah ada menjadi siklik adalah baru, meskipun sisi itu sendiri sudah ada sebelum perbandingan. Siklus dilaporkan sebagai sisi dalam komponen siklik, bukan sebagai jalur siklus yang disebutkan satu per satu.

JSON menyertakan urutan diagnostik yang deterministik, kode, kategori, tingkat keparahan peringatan, identitas, nilai base/target, lokasi (berbasis 1 untuk fungsi), keyakinan, jumlah klasifikasi dan batasan. --fail-on regression keluar dengan 1 untuk temuan baru atau yang memburuk, 0 jika tidak. Error operasional dan hasil tidak lengkap yang diterima secara eksplisit keluar dengan 2, terlepas dari --fail-on. Tanpa flag tersebut, perbandingan lengkap keluar dengan 0. Mode JSON menulis satu dokumen JSON ke stdout, termasuk pada error operasional.

Alat MCP yang sudah ada menerima perbandingan yang sama melalui:

{"base":"master","head":"feature/example","quality":true,"limit":20,"thresholds":{"cyclomatic":10,"min_increase":3}}

report MCP berbagi skema CLI. Jumlah mencakup semua temuan; detail default 20 (maksimum 500), dengan truncated dan total_findings di luar laporan. Gunakan limit: 0 untuk jumlah saja. thresholds menerima nama opsi dalam tabel (cyclomatic, cognitive, function_lines, fan_out), plus min_increase dan allow_stale; opsi yang tidak dikenal ditolak. Filter file/jenis ditolak dalam mode kualitas karena siklikitas dan kopling memerlukan bukti global. Tidak ada alat MCP tambahan yang diekspos. Panggilan kualitas melewati sinkronisasi/reindeks versi otomatis per panggilan; aktivitas independen lain di server yang sudah berjalan mempertahankan perilaku normalnya.

Validasi kesegaran melakukan hash file yang diindeks terhadap blob Git dengan dekoder sumber yang sama seperti pengindeksan, menerima konversi akhir baris LF/CRLF dari checkout Git atau normalisasi commit. File yang tidak cocok/terhapus atau kandidat sumber yang tidak diindeks dilaporkan sebagai basi/tidak lengkap. Penemuan kandidat menghormati aturan pengecualian, file tersembunyi, dan ukuran yang dikonfigurasi; kebijakan ignore atau manifest khusus cabang dapat menjelaskan suatu kandidat, sehingga digambarkan sebagai tidak pasti. --allow-stale (MCP thresholds.allow_stale) mengizinkan inspeksi dengan complete: false dan keluar dengan 2; tidak pernah secara diam-diam menerima bukti basi sebagai hasil CI yang bersih. complete berarti pemeriksaan konten indeks ini lulus, bukan bahwa setiap bahasa atau dependensi telah dianalisis. Pengecualian yang dikonfigurasi dan bahasa yang tidak didukung tetap di luar cakupan; metrik ekstraktor yang dibiarkan nol tidak membuktikan kompleksitas rendah. Indeks harus menggunakan versi/konfigurasi analisis yang sebanding. Validasi tidak mensertifikasi kelengkapan resolver atau mendeteksi penyuntingan manual arbitrer pada baris graf.

Lokasi tidak berpartisipasi dalam identitas. Penggantian nama file yang terdeteksi Git menormalisasi identitas fungsi dan dependensi, sementara nama simbol berkualifikasi mengidentifikasi fungsi. Penggantian nama simbol, pemindahan yang tidak terdeteksi Git, dan overload yang ambigu tidak dapat dicocokkan secara andal: temuan yang tidak cocok secara eksplisit membawa confidence: "unmatched", dan metrik dengan nama/jenis/tanda tangan yang sama yang ambigu dikecualikan dari kedua snapshot dan membuat hasil tidak lengkap. Overload menggunakan tanda tangannya untuk membedakan nama berkualifikasi yang sebaliknya identik. Tinjau pasangan baru/teresolusi yang tidak cocok sebelum menggunakannya sebagai cacat; pasangan tersebut tetap dapat memengaruhi CI. Temuan ukuran fungsi menggunakan rentang sumber, bukan jumlah pernyataan yang dapat dieksekusi. Kebijakan arsitektur, dead-code, keterjangkauan/cakupan pengujian dan regresi ukuran modul ditunda.

Snapshot dibaca secara berurutan dalam transaksi baca database. Badan simbol dimuat satu file terindeks pada satu waktu; hanya catatan metrik ringkas yang bertahan ke dalam perbandingan. Adjacency file dan algoritma SCC iteratif yang sudah ada memerlukan ruang/waktu O(file + dependensi file teresolusi) untuk analisis siklus. Tidak ada siklus individual yang disebutkan satu per satu. Validasi menggunakan satu proses batch Git per snapshot dan satu blob terdekode pada satu waktu (maksimum 64 MiB); ia membaca konten terindeks plus metadata pohon Git, tanpa memindai working tree. Biaya total juga berskala dengan byte sumber dan simbol yang diindeks; ini sengaja menukar sebagian I/O untuk kesegaran yang dapat diverifikasi tanpa provenans commit. Tidak ada cache, kumpulan worker, atau pekerjaan latar belakang yang dibuat oleh perbandingan. Laporan JSON besar bisa substansial; gunakan jumlah MCP atau detail terbatas ketika anggaran token penting.

Sumber Daya MCP

Empat sumber daya diekspos melalui resources/list dan resources/read:

• tokensave://status -- statistik graf sebagai JSON
• tokensave://files -- pohon file terindeks yang dikelompokkan berdasarkan direktori
• tokensave://overview -- ringkasan proyek dengan distribusi bahasa dan jenis simbol
• tokensave://branches -- cabang yang dilacak beserta ukuran DB dan info induk

Pelacakan Token

tokensave mengukur token yang dihematnya pada setiap panggilan alat MCP. Setiap respons alat menyertakan baris tokensave_metrics: before=N after=M yang menunjukkan berapa banyak token file mentah yang dihindari oleh panggilan spesifik tersebut.

Mematikan pelaporan. Baris metrik, bersama dengan sebuah kalimat di instructions MCP, meminta agen untuk melaporkan penghematan kepada Anda — yang berarti model menghabiskan token output untuk menarasikan penghematan yang dibuat tokensave pada token input. Token output adalah jenis yang lebih mahal, jadi jika agen Anda menyebut tokensave hampir di setiap giliran, narasi itu dapat mengimbangi keuntungannya (#356). Setel report_savings ke false di .tokensave/config.json, atau variabel lingkungan TOKENSAVE_REPORT_SAVINGS untuk menimpanya per-run (nilai apa pun mengaktifkannya kecuali 0, false, no, off, atau kosong). Baris metrik dan instruksinya sama-sama hilang; tokensave install juga berhenti menulis aturan pelaporan ke file prompt agen. Pengukuran tidak tersentuh dengan cara apa pun — setiap panggilan tetap masuk ke buku besar penghematan, sehingga tokensave gain, tokensave list, status dan monitor terus melaporkan persis seperti sebelumnya. Default tetap true.

Hanya alat inti yang terdaftar secara default. Klien MCP mengirim skema setiap alat yang terdaftar pada setiap giliran, sebelum alat apa pun dipanggil. Permukaan tokensave lengkap sekitar 89 KB skema, yang pada model berkonteks kecil bisa lebih dari setengah jendela (#576). Jadi tools/list hanya mengirim alat inti: context, search, status, read, body, files, callers, callees, impact, str_replace dan multi_str_replace (sekitar 17 KB dengan tokensave_more). Instruksi initialize menamai alat-alat ini dan area yang dapat didaftar oleh tokensave_more, sehingga klien yang menunda skema alat tetap tahu sisanya ada. Pengaturan ini memilih apa yang didaftar server, bukan apa yang dapat dijalankannya: alat yang tidak terdaftar tetap menjawab panggilan berdasarkan nama, sehingga daftar izin agen dan hook tetap berfungsi. Untuk mendaftar semua alat, setel "tools": "full" di .tokensave/config.json, atau TOKENSAVE_TOOLS=full di lingkungan server MCP; variabel lingkungan menang atas file. "tools": "full" yang ditulis oleh 7.13.0, yang menuliskannya ke setiap konfigurasi yang disimpannya, dibaca sebagai default lama; setel ulang setelah upgrade untuk mempertahankan daftar lengkap.

Dengan toolset inti, server juga mendaftar tokensave_more. Panggilan dengan area (analysis, edit, git, memory, navigate atau all) mendaftar alat area tersebut untuk sisa sesi, dan server mengirim notifications/tools/list_changed agar klien mengambil daftar lagi. Sesi hanya membayar untuk area yang digunakannya: area git menambahkan sekitar 6 KB. Klien yang mengabaikan list_changed mempertahankan daftar inti. tokensave install memberikan tokensave_more bersama semua alat lainnya, sehingga tidak meminta konfirmasi; instalasi dari sebelum rilis ini meminta konfirmasi sekali, hingga tokensave reinstall atau resinkronisasi upgrade menyegarkan daftar izin.

Observabilitas biaya

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

Mengurai transkrip sesi Claude Code (~/.claude/projects/**/*.jsonl), mengklasifikasikan setiap giliran API ke salah satu dari 13 kategori tugas, menghitung biaya dolar menggunakan harga model, dan menyimpan hasilnya di ~/.tokensave/global.db untuk kueri agregat yang cepat. Harga disegarkan dari LiteLLM setiap 24 jam dan kembali ke tabel tertanam saat offline.

Header tokensave status menyertakan baris biaya yang menunjukkan pengeluaran hari ini, total 7 hari, dan rasio efisiensi (token dihemat / total token). TUI tokensave monitor menampilkan panel biaya langsung bersama feed penghematan. Di akhir setiap sesi Claude Code, handler hook_stop mencetak tanda terima satu baris ke terminal.

Kategori klasifikasi tugas: Coding, Debugging, Feature Dev, Refactoring, Testing, Exploration, Planning, Delegation, Git Ops, Build/Deploy, Brainstorming, Conversation, General. Klasifikasi bersifat deterministik (pencocokan pola pada nama alat dan perintah Bash), tidak memerlukan panggilan LLM, dan diadaptasi dari AgentSeal/codeburn.

Monitor langsung

tokensave monitor

TUI global yang menampilkan panggilan alat MCP dari semua proyek secara real time, melalui buffer cincin memory-mapped bersama di ~/.tokensave/monitor.mmap. Setiap entri menampilkan nama proyek, nama alat, dan delta token. Panel biaya di bagian atas menampilkan pengeluaran hari ini, penghematan, efisiensi, dan model teratas (disegarkan setiap 30 detik).

Diagnostik memori

tokensave memory [--clean]

Laporan memori seluruh mesin untuk setiap proses tokensave (server MCP, sinkronisasi, proses indeks), melalui tabel memory-mapped bersama di ~/.tokensave/memory.mmap. Setiap instans mengambil sampel RSS-nya sendiri secara best-effort saat startup, per panggilan alat MCP, dan di sekitar fase sinkronisasi/resolusi, sehingga laporan menunjukkan RSS saat ini dan puncak beserta fase yang menghasilkan puncak tersebut — data yang diperlukan untuk mengatribusikan penggunaan memori tinggi (lihat #253). Baris ditandai alive, dead (proses yang dimatikan OOM meninggalkan puncak/fasenya sebagai catatan forensik), atau orphan (masih berjalan tetapi di-reparent ke init). --clean membersihkan slot yang mati. PEAK PHASE menamai sampel tertinggi, jadi presisinya hanya sepresisi pengambilan sampel. Sinkronisasi inkremental mencatat, secara berurutan: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. Indeks penuh mencatat index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done.

Masing-masing dicatat setelah pekerjaan yang dinamainya. Dulu semuanya dicatat sebelum pekerjaan tersebut, sehingga setiap sampel melaporkan RSS langkah sebelumnya di bawah label langkah berikutnya — yang mengatribusikan 73 MiB ke pemuatan node yang sebenarnya milik pemuatan referensi yang belum terselesaikan, sebuah langkah tanpa sampel sama sekali, dan mengarahkan investigasi memori ke subsistem yang salah selama berbulan-bulan (#409). Jika Anda menambahkan fase, ambil sampel setelah pekerjaan, bukan sebelumnya, dan tambahkan satu untuk setiap langkah yang cukup besar untuk menampung puncaknya.

Penghitung sesi dan masa pakai

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 menampilkan statistik indeks proyek, rincian bahasa, baris biaya (hari ini / 7h / efisiensi), serta total masa pakai proyek + seluruh dunia:

Penghitung seluruh dunia

Semua pengguna tokensave berkontribusi ke penghitung agregat anonim. tokensave status menampilkan total proyek Anda dan total seluruh dunia. Unggahan hanya mengirim satu angka (mis. 4823) tanpa informasi pengenal apa pun. Nonaktifkan dengan tokensave disable-upload-counter.

Kesegaran Indeks

tokensave menjaga graf tetap mutakhir tanpa daemon latar belakang atau pemantau berkas tingkat OS.

Pemeriksaan kedaluwarsa sesuai permintaan. Setiap pemanggilan alat MCP memeriksa apakah ada berkas terindeks yang dimodifikasi sejak sinkronisasi terakhir. Jika ditemukan berkas kedaluwarsa, berkas tersebut diekstraksi ulang sebelum respons alat dikembalikan. Jeda 30 detik mencegah pemanggilan beruntun menelusuri ulang pohon pada setiap penekanan tombol.

Sinkronisasi pengejaran saat terhubung. Saat server MCP dimulai, ia langsung menjalankan sinkronisasi pengejaran non-blocking yang mengambil perubahan apa pun yang dilakukan saat tidak ada agen terpasang — sebuah git pull, suntingan IDE, langkah build — sehingga pemanggilan alat pertama dalam sesi melihat indeks yang segar.

Kerja multi-agen dan git worktree. Ketika beberapa agen bekerja pada proyek yang sama secara bersamaan, asumsi kuatnya adalah setiap agen beroperasi di git worktree-nya sendiri. Worktree adalah checkout filesystem independen dari repositori yang sama: agen A dan agen B masing-masing memiliki salinan sendiri dari setiap berkas, sehingga mereka tidak pernah menimpa suntingan yang sedang berlangsung satu sama lain. tokensave secara otomatis mendeteksi ketika kueri berasal dari worktree yang bersarang di dalam checkout utama dan menyajikan hasil dari graf cabang yang benar. Perubahan terakumulasi secara independen dan pada akhirnya direkonsiliasi melalui git merge atau rebase — proses yang sama yang digunakan untuk pengembangan paralel lainnya. Desain ini menghindari kompleksitas dan mode kegagalan dari penguncian lintas agen pada direktori bersama yang dapat berubah.

Alur kerja khusus CLI. Jika Anda menjalankan perintah tokensave tanpa agen terpasang (tanpa server MCP), pemeriksaan kedaluwarsa tidak berjalan di antara perintah. Pasang git hook agar indeks tetap segar secara otomatis setelah setiap commit atau clone:

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

Meningkatkan dari 5.x

Perintah mandiri tokensave daemon dan autostart launchd/systemd/Windows Service-nya dihapus pada 6.0.0. Pemantau berkas tingkat OS tertanam yang menggantikan daemon itu sendiri dihapus pada 6.1.1 (menyebabkan CPU dan memori lepas kendali pada monorepo besar dengan pohon node_modules atau target yang dalam). Model kedaluwarsa sesuai permintaan di atas adalah desain saat ini.

Jika Anda masih memiliki autostart daemon dari 5.x, hapus:

• 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 (dari terminal dengan hak administrator)

Jika Anda tidak ingat nama persisnya: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

Peningkatan Mandiri

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 mengunduh biner platform yang benar dari rilis GitHub dan mengganti biner yang sedang berjalan di tempat. Mendukung kanal stabil dan beta secara independen.

Pemberian versi & peningkatan

Nomor versi tokensave terlihat seperti SemVer tetapi tidak mengikutinya: komponen yang berubah mengodekan pemeliharaan yang diperlukan pembaruan, yang dilakukan tokensave secara otomatis pada peluncuran berikutnya — Anda tidak pernah menjalankan instalasi ulang atau pengindeksan ulang secara manual.

Instalasi ulang global. Pada eksekusi pertama build minor atau major baru, tokensave diam-diam menjalankan ulang install untuk setiap agen yang telah didaftarkannya, sehingga konfigurasi agen selalu menunjuk ke biner saat ini dan mengekspos kumpulan alat saat ini. Kenaikan patch melewati ini — penanda versi yang berjalan cukup dimajukan.

Instalasi ulang ini benar-benar senyap: keluaran penyiapan per agen yang Anda lihat dari tokensave install eksplisit ditekan di sini, sehingga tidak pernah muncul di hadapan tokensave init atau tokensave sync biasa. Jika konfigurasi agen tidak dapat disegarkan — aplikasinya tidak terpasang, atau konfigurasinya berada di lokasi hanya-baca — Anda mendapat satu baris yang menyebutkan agen yang gagal:

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

Jalankan tokensave install untuk melihat kesalahan yang mendasarinya. Penanda versi tetap dimajukan dalam kedua kasus, sehingga jalur konfigurasi yang tidak akan pernah bisa ditulis dilaporkan sekali per peningkatan alih-alih dicoba ulang pada setiap perintah berikutnya.

Pengindeksan ulang paksa per proyek (hanya major). Kenaikan major berarti indeks proyek harus dibangun ulang. tokensave melakukannya secara malas dan per proyek: pada pemanggilan alat MCP pertama dalam sebuah proyek setelah peningkatan major, ia menjalankan pengindeksan ulang penuh di latar belakang (setara dengan tokensave sync --force) yang tidak pernah memblokir respons alat.

Fallback Brew / cargo. Peningkatan eksternal yang mengganti biner di luar tokensave upgrade — brew upgrade tokensave atau cargo install tokensave — dideteksi dengan cara yang sama: jika versi yang berjalan lebih baru daripada versi terakhir yang melakukan instalasi, instalasi ulang berjalan pada peluncuran berikutnya seperti halnya setelah peningkatan mandiri.

Lihat TOKENSAVE-VERSIONING.md untuk alasan tokensave menyimpang dari SemVer (mengodekan pemeliharaan dalam versi adalah yang memungkinkan peningkatan tanpa sentuhan), mekanisme penanda, versi skema basis data yang independen, dan aturan pemelihara untuk merilis versi.

Referensi CLI

tokensave init [path]              # Initialize a new project (full index)
tokensave init --cpu-usage low     # Initialize and pin a CPU profile for this project (no benchmark)
tokensave config benchmark         # Run or reuse the machine-level hardware benchmark
tokensave config benchmark --show  # Show the saved benchmark and settings (never measures)
tokensave config benchmark --force # Measure this machine again
tokensave config benchmark --reset # Delete the saved benchmark
tokensave tune [path] [--dry-run]  # Re-benchmark, save globally, update a pinned cpu_usage
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 verify [path]            # Read-only index integrity and source-stat checks
tokensave verify [path] --deep --json # Full SQLite checks and bounded source hashing
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

Jalankan pemeriksaan kesehatan menyeluruh atas instalasi tokensave Anda:

tokensave doctor

Memeriksa: lokasi biner, indeks proyek, DB global, konfigurasi pengguna, integrasi agen (server MCP, hook, izin, aturan prompt), dan konektivitas jaringan. Jika ada izin alat yang hilang setelah peningkatan, ia memberi tahu Anda untuk menjalankan tokensave install. Gunakan --agent untuk memeriksa agen tertentu saja.

Doctor juga memvalidasi bahwa setiap hook yang terpasang menggunakan subperintah tokensave yang benar dan secara otomatis memperbaiki hook yang rusak.

Cara Kerjanya dengan Claude Code

Setelah dikonfigurasi, Claude Code secara otomatis menggunakan tokensave alih-alih membaca berkas mentah ketika perlu memahami basis kode Anda. Tiga lapisan saling memperkuat:

Hasilnya: Claude mendapatkan pemahaman kode yang sama dengan token jauh lebih sedikit. Agen Explore tipikal membaca 20-50 berkas; tokensave mengembalikan simbol, relasi, dan cuplikan kode yang relevan dari indeks yang telah dibangun sebelumnya.

Panggilan Jaringan & Privasi

Fungsi inti tokensave (pengindeksan, pencarian, kueri graf, server MCP) 100% lokal -- kode Anda tidak pernah meninggalkan mesin Anda.

Unggahan penghitung seluruh dunia mengirim satu HTTP POST dengan body JSON seperti {"amount": 4823}. Tanpa cookie, tanpa pelacakan, tanpa ID pengguna. Cloudflare Worker mencatat negara dari alamat IP Anda (diturunkan dari header permintaan) untuk statistik geografis agregat -- alamat IP Anda yang sebenarnya tidak disimpan.

Penyegaran harga model mengambil berkas JSON publik dari GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) untuk menjaga harga model Claude tetap mutakhir bagi tokensave cost. Tidak ada data yang dikirim -- ini adalah HTTPS GET biasa. Responsnya di-cache di ~/.tokensave/pricing.json selama 24 jam. Jika pengambilan gagal, tokensave menggunakan tabel harga yang dikompilasi di dalamnya.

50+ Bahasa

tokensave mendukung lebih dari 50 bahasa pemrograman yang diorganisasi ke dalam tiga tingkatan yang dikendalikan oleh feature flag Cargo. Setiap tingkatan mencakup semua bahasa dari tingkatan di bawahnya. Header Markdown diekstraksi sebagai node Module dengan edge Contains hierarkis sehingga struktur dokumen berpartisipasi dalam kueri graf bersama kode sumber.

Lite -- --no-default-features

Selalu dikompilasi. Biner terkecil untuk bahasa paling populer, plus Svelte dan Astro (ekstraksi blok skrip melalui ekstraktor TypeScript, tanpa dependensi grammar tambahan).

Medium (Lite + 9 lainnya) -- --features medium

Pintasan Slim kustom dan kompilasi bahasa tersemat tidak didukung. Variabel lokal yang disediakan Rails saat render tidak dapat dibedakan dari pemanggilan helper biasa; nama yang ditetapkan atau diikat dalam templat dikecualikan secara konservatif. Hubungan controller-ke-view dan partial-render memerlukan pengkabelan semantik Rails terpisah.

Full (Medium + everything else) -- default

Bahasa individual juga dapat dipilih secara terpisah tanpa tier penuh:

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

Semua ekstraktor berbagi kedalaman yang sama: fungsi, kelas, metode, field, impor, graf pemanggilan, rantai pewarisan, docstring, metrik kompleksitas, ekstraksi dekorator/anotasi, dan pelacakan dependensi lintas file.

HTML dan CSS adalah pengecualian, karena keduanya tidak memiliki simbol yang dapat dipanggil. HTML mencatat elemen yang membawa id, elemen kustom, serta stylesheet dan skrip yang ditarik oleh halaman; CSS mencatat selektor kelas dan id, properti kustom, nama @keyframes, dan @import. Keduanya tidak me-resolve atribut class="..." ke aturan stylesheet: nama kelas adalah kata biasa, dan mencocokkannya berdasarkan nama telanjang di seluruh proyek akan menciptakan edge alih-alih menemukannya.

tokensave vs CodeGraph

tokensave adalah penulisan ulang Rust dari awal atas CodeGraph (Node.js/TypeScript). Keduanya membangun graf kode semantik untuk agen pengkodean AI, tetapi keduanya berbeda secara signifikan dalam cakupan dan kemampuan.

CodeGraph memelopori pendekatan ini dan tetap menjadi pilihan yang solid jika Anda lebih menyukai perkakas npm dan hanya membutuhkan integrasi Claude Code. tokensave memperluas konsep ini dengan analisis yang lebih mendalam, lebih banyak agen, dukungan multi-branch, dan binary native tanpa dependensi runtime.

Untuk perbandingan terperinci terhadap CodeGraph, Dual-Graph (GrapeRoot), code-review-graph, dan OpenWolf, lihat docs/COMPARABLE-TOOLS.md.

Halaman perbandingan berdampingan (masing-masing menyatakan di mana alat lain lebih baik): Serena · code-review-graph · Graphify · CodeGraph · token-savior · GrapeRoot · LeanCTX · OpenWolf — indeks di tokensave.dev/vs.

Mengapa tokensave Dibandingkan Alternatif

Beberapa alat mengurangi penggunaan token untuk agen pengkodean AI. Berikut alasan tokensave menonjol.

Binary native tunggal, tanpa dependensi

Sebagian besar alternatif memerlukan runtime: Python, Node.js, atau keduanya. tokensave dikirim sebagai binary Rust tunggal dengan semua 50+ tata bahasa tree-sitter dibundel (unduhan terkompresi ~25 MB). Tidak ada lagi yang perlu dipasang -- dan tidak seperti alat berbasis LSP seperti Serena, tidak ada language server yang perlu dipasang, dijalankan, atau dipanaskan per bahasa. Dua alat kini menyamai tokensave dalam hal pengemasan: CodeGraph membundel runtime-nya sendiri, dan LeanCTX juga merupakan binary Rust tunggal.

Kecerdasan kode paling mendalam

tokensave bekerja pada tingkat simbol: fungsi, struct, field, edge pemanggilan, hierarki tipe, metrik kompleksitas. Alternatif seperti Dual-Graph (GrapeRoot) bekerja pada tingkat file -- mereka tahu file mana yang ada tetapi tidak dapat menjawab "siapa yang memanggil fungsi ini?" atau "apa yang rusak jika saya mengubah struct ini?" 80+ alat MCP khusus tokensave mencakup traversal graf pemanggilan, analisis dampak, deteksi kode mati, pemetaan pengujian, pratinjau rename, hierarki tipe, deteksi dependensi sirkular, peringkat kompleksitas, analitik kesehatan kode (Gini, DSM, kedalaman dependensi, celah pengujian berbobot risiko), primitif edit atomik, dan lainnya. Alat graf terdekat yang sebanding, code-review-graph, mengekspos 30; beberapa lainnya mengekspos kurang dari 10 berdasarkan desain yang disengaja.

Dukungan agen terluas

Lebih dari selusin integrasi agen pengkodean AI dengan format konfigurasi native per agen. Tidak ada alat lain yang mencakup begitu banyak agen dengan integrasi sedalam ini. Claude Code mendapatkan hook, aturan prompt, dan izin alat yang diizinkan otomatis. Kiro mendapatkan konfigurasi MCP global, tokensave.md steering yang dimuat sebagai resource, agen terkelola dengan persetujuan alat bawaan/tokensave yang permisif, dan hook untuk guardrail delegasi plus sinkronisasi pasca-tulis. Agen lain mendapatkan pendaftaran server MCP dalam format konfigurasi native mereka.

Pengindeksan multi-branch

Satu-satunya alat di ruang ini dengan database graf per-branch opsional serta diff dan pencarian lintas branch. Saat diaktifkan, berpindah branch menjadi instan -- tanpa perlu pengindeksan ulang.

Pelacakan token per panggilan

Satu-satunya alat yang melaporkan secara tepat berapa banyak token yang dihemat oleh setiap panggilan alat MCP individual, plus monitor TUI langsung di semua proyek dan penghitung seumur hidup.

Sepenuhnya open source

Rust berlisensi MIT, dapat diaudit dari ujung ke ujung. Mesin inti Dual-Graph (graperoot di PyPI) bersifat proprietary -- Anda tidak dapat melihat apa yang dilakukannya dengan graf kode Anda. OpenWolf berlisensi AGPL-3.0, yang mewajibkan karya turunan untuk di-open-source-kan.

Performa

Benchmark indeks penuh pada basis kode campuran Rust/Java/Scala dengan 1.782 file (57K node, 103K edge):

Pemecahan Masalah

"tokensave not initialized"

Direktori .tokensave/ tidak ada di proyek Anda.

tokensave init

Server MCP tidak terhubung

Agen AI tidak melihat alat tokensave.

1. Pastikan konfigurasi agen menyertakan server MCP tokensave (jalankan tokensave doctor)
2. Mulai ulang agen sepenuhnya
3. Periksa bahwa tokensave ada di PATH Anda: which tokensave

Simbol hilang dalam pencarian

• Jalankan tokensave sync untuk memperbarui indeks
• Periksa bahwa bahasa tersebut didukung (lihat tabel di atas)
• Verifikasi file tidak dikecualikan oleh .gitignore

Pengindeksan lambat

Proyek besar membutuhkan waktu lebih lama pada indeks penuh pertama.

• Proses berikutnya menggunakan sinkronisasi inkremental dan jauh lebih cepat
• Gunakan tokensave sync (bukan --force) untuk pembaruan sehari-hari
• Staleness diperiksa secara otomatis pada setiap panggilan alat MCP selama agen terhubung

Menonaktifkan tokensave untuk proyek tertentu

Jika sebuah proyek terlalu besar dan tokensave menggunakan terlalu banyak RAM, Anda dapat menonaktifkan server MCP per proyek dengan menetapkan TOKENSAVE_DISABLE_SERVER=true di environment-nya. Server keluar dengan bersih tanpa inisialisasi.

Claude Code — tambahkan ke .claude/settings.json proyek Anda:

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

Agen lain — atur variabel lingkungan di konfigurasi apa pun yang digunakan agen Anda untuk menjalankan server MCP.

Anda juga dapat mengaturnya secara global melalui shell (TOKENSAVE_DISABLE_SERVER=true claude), tetapi ini menonaktifkan server MCP tokensave untuk setiap proyek dalam sesi tersebut.

DISABLE_TOKENSAVE=true tetap didukung sebagai alias kompatibilitas yang sudah usang untuk konfigurasi yang dibuat sebelum variabel ini diberi namespace.

Asal

Proyek ini adalah port Rust dari implementasi TypeScript CodeGraph asli oleh @colbymchenry. Port ini mempertahankan arsitektur dan antarmuka alat MCP yang sama sambil memanfaatkan Rust untuk performa dan binding tree-sitter native.

Membangun

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

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

Perintah pengembangan menggunakan build debug; instalasi hanya menggunakan output rilis yang dioptimalkan (cargo install --path . --locked). target/debug tidak pernah menjadi input instalasi.

Riwayat Bintang

Sponsor

Penandatanganan kode gratis di Windows disediakan oleh SignPath.io, sertifikat oleh SignPath Foundation

Lisensi

Lisensi MIT -- lihat LICENSE untuk detailnya.

tokensave.dev