tokensave

Semantic Code Intelligence for AI Coding Agents

Fewer tokens • Fewer tool calls • 100% local

ทำไมต้อง tokensave?

เอเจนต์เขียนโค้ดด้วย AI สิ้นเปลืองโทเค็นไปกับการสำรวจโค้ดเบส การ grep, glob และอ่านไฟล์ทุกครั้งมีค่าใช้จ่าย ในงานที่ซับซ้อน เอเจนต์จะสร้างเอเจนต์ย่อย Explore หลายตัวเพื่อสแกนไฟล์หลายร้อยไฟล์เพียงเพื่อสร้างบริบท

tokensave มอบกราฟความรู้เชิงความหมายที่จัดทำดัชนีไว้ล่วงหน้าให้เอเจนต์ แทนที่จะสแกนไฟล์ เอเจนต์จะสอบถามกราฟและได้รับคำตอบที่มีโครงสร้างทันที -- สัญลักษณ์ที่ถูกต้อง ความสัมพันธ์ และซอร์สโค้ด ในการเรียกครั้งเดียว

วิธีการทำงาน

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

ไม่มี tokensave: เอเจนต์ใช้ grep, glob และ Read เพื่อสแกนไฟล์ -- ใช้ API หลายครั้ง สิ้นเปลืองโทเค็นสูง

มี tokensave: เอเจนต์สอบถามกราฟผ่านเครื่องมือ MCP -- ผลลัพธ์ทันที ประมวลผลในเครื่อง ใช้โทเค็นน้อยลง

คุณสมบัติหลัก

เริ่มต้นอย่างรวดเร็ว

1. ติดตั้ง

Homebrew (macOS):

brew install aovestdipaperino/tap/tokensave

Scoop (Windows):

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

Cargo / cargo-binstall (ทุกแพลตฟอร์ม):

# Fast install prebuilt binary without compiling:
cargo binstall tokensave

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

ไบนารีที่คอมไพล์ไว้ล่วงหน้า (Linux, Windows, macOS):

ดาวน์โหลดจาก รุ่นล่าสุด และวางไบนารีใน PATH ของคุณ

2. กำหนดค่าเอเจนต์ของคุณ

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

เอเจนต์แต่ละตัวจะลงทะเบียนเซิร์ฟเวอร์ MCP ในรูปแบบการกำหนดค่าดั้งเดิมของมัน Claude Code ยังได้รับ hook PreToolUse (บล็อกเอเจนต์ Explore ที่สิ้นเปลือง), hook UserPromptSubmit, hook Stop, กฎพรอมต์ใน CLAUDE.md และสิทธิ์เครื่องมือที่อนุญาตอัตโนมัติ Kiro ได้รับการกำหนดค่า MCP ทั่วโลก, tokensave.md การนำทางที่โหลดเป็นทรัพยากร และเอเจนต์เริ่มต้นที่จัดการโดย tokensave พร้อมการอนุมัติเครื่องมือในตัว/tokensave ที่อนุญาต, hook การป้องกันการมอบหมาย และการซิงค์หลังการเขียน; เอเจนต์ Kiro ที่ผู้ใช้จัดการจะถูกเก็บรักษาไว้

การติดตั้ง OMP ทั่วโลกกำหนดเป้าหมายโปรไฟล์ที่รายงานโดย omp config path แบบเปล่า, เขียน <resolved-agent-dir>/mcp.json และ <resolved-agent-dir>/rules/tokensave.md ส่งออก OMP_PROFILE หรือ PI_PROFILE ที่เข้ากันได้ของ OMP เมื่อติดตั้งลงในโปรไฟล์ที่มีชื่อ; ตัวแก้ของ OMP ยังให้เกียรติ PI_CONFIG_DIR และ PI_CODING_AGENT_DIR tokensave ไว้วางใจตัวแก้ดั้งเดิมนั้นแทนที่จะทำซ้ำตรรกะโปรไฟล์ของ OMP tokensave ติดตั้งกฎ MCP และคำแนะนำสำหรับ OMP; ไม่ได้ติดตั้งการบังคับใช้ hook ของ OMP

การเปลี่ยนแปลงทั้งหมดเป็น idempotent -- ปลอดภัยที่จะรันอีกครั้งหลังอัปเกรด หลังการตั้งค่าเอเจนต์ คุณจะได้รับข้อเสนอ hook git post-commit และ post-checkout ทั่วโลก tokensave uninstall ลบ hook เหล่านั้นพร้อมกับการผสานรวมเอเจนต์; ส่ง --keep-git-hooks เพื่อปล่อยไว้ หรือจัดการด้วยตัวเองด้วย tokensave githooks

การติดตั้งเฉพาะโปรเจกต์

โดยค่าเริ่มต้น tokensave install ลงทะเบียนเซิร์ฟเวอร์ MCP ใน การกำหนดค่าเอเจนต์ทั่วโลก ของคุณ (เช่น ~/.claude.json) หากต้องการลงทะเบียน tokensave สำหรับเฉพาะโปรเจกต์ปัจจุบันแทน ให้เพิ่ม --local:

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

สิ่งนี้เขียนการกำหนดค่าที่ขอบเขตโปรเจกต์ซึ่งคุณสามารถคอมมิตและแชร์กับทีมของคุณได้ สำหรับ Claude นั่นคือ ./.mcp.json, ./.claude/settings.json และ ./CLAUDE.md; OMP ใช้ ./.omp/mcp.json และ ./.omp/rules/tokensave.md โดยไม่เรียกใช้ CLI ของ OMP เอเจนต์ที่รองรับ: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank (แต่ละตัวเขียนไฟล์โปรเจกต์ของตัวเอง เช่น .cursor/mcp.json, .factory/mcp.json, .gemini/settings.json, .zed/settings.json, opencode.json, .roo/mcp.json, .kiro/settings/mcp.json, .augment/settings.json, .omp/mcp.json, .mcp.json สำหรับ plank) เอเจนต์อื่นไม่มี config ที่ขอบเขตโปรเจกต์และรายงานข้อผิดพลาดด้วย --local

ลบการติดตั้งเฉพาะโปรเจกต์ด้วย tokensave uninstall --local

3. จัดทำดัชนีโปรเจกต์ของคุณ

cd /path/to/your/project
tokensave init

สิ่งนี้สร้างไดเรกทอรี .tokensave/ พร้อมฐานข้อมูลกราฟความรู้ การเริ่มต้นและการซิงค์เป็นคำสั่งแยก: init เป็นการเลือกใช้ครั้งเดียวต่อโปรเจกต์ ในขณะที่ sync อัปเดตเฉพาะโปรเจกต์ที่เริ่มต้นแล้วเท่านั้น สิ่งนี้ป้องกันไม่ให้ hook git ทั่วโลกสร้างฐานข้อมูลใน repo ที่คุณไม่เคยตั้งใจจะจัดทำดัชนี หลัง init, ใช้ tokensave sync เพื่ออัปเดตแบบเพิ่มหน่วย -- เฉพาะไฟล์ที่เปลี่ยนแปลงเท่านั้นที่ถูกจัดทำดัชนีใหม่

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

การซิงค์ที่ทนทานต่อการขัดข้อง

ไวยากรณ์ tree-sitter เป็นโค้ด C/C++ ที่คอมไพล์ บางครั้งมันพบการยืนยันภายในหรือยุติโพรเซสด้วยพาธที่การจัดการ panic ของ Rust ไม่สามารถสกัดกั้นได้ ตั้งแต่ v4.3.0 ทุกไฟล์ถูกแยกวิเคราะห์ภายในโพรเซสย่อย worker อายุสั้น: หากไวยากรณ์ segfault, เรียก abort() หรือพบ stack overflow เฉพาะ worker ตาย พูลสร้างใหม่ ไฟล์ที่ผิดถูกบันทึกและข้าม และ sync ดำเนินต่อไป

worker เป็นคำสั่งย่อย extract-worker ที่ซ่อนอยู่ซึ่งตรวจสอบสิทธิ์กับพาเรนต์ผ่านโทเค็น 256 บิตต่อการสร้าง จำเป็นต้องใช้ทั้งเป็นตัวแปรสภาพแวดล้อม TOKENSAVE_WORKER_TOKEN และเป็น 32 ไบต์แรกที่ได้รับบน stdin การเรียกโดยตรงโดยผู้ใช้ล้มเหลว ค่าเริ่มต้นเป็น worker available_parallelism(); เลือกไม่ใช้ด้วย TOKENSAVE_DISABLE_SUBPROCESS=1

พื้นฐานการแก้ไข (tokensave_str_replace, tokensave_insert_at ฯลฯ) ยังคงรันในโพรเซส: พวกมันกำหนดเป้าหมายทีละไฟล์ที่ค่าใช้จ่ายโพรเซสย่อยจะครอบงำ และการขัดข้องของตัวแยกที่นั่นจะมองเห็นได้ทันทีต่อเอเจนต์

การจัดทำดัชนีหลายสาขา (ไม่บังคับ)

tokensave สามารถรักษากราฟโค้ดแยกต่อสาขา git ได้ เมื่อเปิดใช้งาน การสลับสาขาไม่เคยให้ผลลัพธ์ที่เก่าและไม่เคยจัดทำดัชนีไฟล์ที่คุณแยกวิเคราะห์แล้วบนสาขาอื่นใหม่ การติดตามหลายสาขาเป็นแบบเลือกใช้ -- หากไม่มี tokensave ใช้ฐานข้อมูลเดียวสำหรับทุกสาขา

วิธีการทำงาน

เมื่อคุณติดตามสาขา tokensave คัดลอกฐานข้อมูลบรรพบุรุษที่ใกล้ที่สุดและซิงค์เฉพาะไฟล์ที่แตกต่าง ซึ่งหมายความว่าการติดตามสาขาคุณสมบัติจาก main เกือบจะทันที -- มันแยกวิเคราะห์เฉพาะไฟล์ที่คุณเปลี่ยนแปลง

คำสั่ง CLI

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

เครื่องมือ MCP ข้ามสาขา

เครื่องมือ MCP สามรายการเปิดใช้งานการสอบถามข้ามสาขาโดยไม่ต้องสลับ checkout:

• tokensave_branch_search -- ค้นหาสัญลักษณ์ในกราฟของสาขาอื่น
• tokensave_branch_diff -- เปรียบเทียบกราฟโค้ดระหว่างสองสาขา: สัญลักษณ์ที่เพิ่ม ลบ และเปลี่ยนแปลง (ลายเซ็นต่างกัน) รองรับตัวกรองไฟล์และชนิด
• tokensave_branch_list -- แสดงรายการสาขาที่ติดตามพร้อมขนาด DB, สาขาพาเรนต์ และเวลาซิงค์

การสำรองสาขา

เมื่อเซิร์ฟเวอร์ MCP ไม่พบฐานข้อมูลสำหรับสาขาปัจจุบัน มันให้บริการจากฐานข้อมูลของสาขาบรรพบุรุษที่ใกล้ที่สุดและรวมคำเตือนในการตอบสนองเครื่องมือทุกครั้งที่แนะนำให้รัน tokensave branch add

การติดตามสาขาอัตโนมัติ (v7.3.0)

เมื่อโหมดหลายสาขาถูกบูตสแตรป (tokensave branch add แรกที่ทำด้วยตนเองสร้างเมตาดาต้าสาขา) สาขาใหม่สามารถติดตามได้โดยอัตโนมัติแทนที่จะสำรองไปยังฐานข้อมูลบรรพบุรุษ กลไกอิสระสองกลไกครอบคลุมสิ่งนี้; โปรเจกต์ในโหมด DB เดียวไม่ได้รับผลกระทบ และไม่มีกลไกใดแตะต้องฐานข้อมูลของสาขาเริ่มต้น Git hook (เมื่อมีการสลับ branch) hook post-checkout ที่ tokensave install ติดตั้งไว้จะรู้จักการสลับ branch (ซึ่งต่างจากการสลับไฟล์) และรัน tokensave branch add ในเบื้องหลัง คำสั่งนั้นจะไม่ทำอะไรเลยเมื่อ branch ถูกติดตามอยู่แล้วหรือเป็น branch เริ่มต้น ดังนั้นการสลับระหว่าง branch ที่รู้จักกันโดยทั่วไปจึงไม่มีค่าใช้จ่าย การ checkout ครั้งแรกของ git clone ใหม่และ git worktree add ใหม่ก็เป็นการ checkout branch เช่นกัน และอาจไปอยู่บน branch ที่ไม่ใช่ branch เริ่มต้น (git clone -b feature, git worktree add -b feature); ในกรณีนั้น hook จะรัน tokensave init ก่อนแล้วจึงรัน tokensave branch add ตามลำดับ hook ที่เขียนโดยเวอร์ชันก่อนหน้าจะคงเนื้อหาที่ติดตั้งไว้ตั้งแต่แรก — ตัวติดตั้งจะไม่เขียนทับ hook ที่มีอยู่ — ดังนั้นในการติดตั้งเหล่านั้น worktree ใหม่ยังคงต้องใช้ auto_track ด้านล่าง หรือรัน tokensave branch add ด้วยตนเอง

การติดตามอัตโนมัติเมื่อเปิด (เลือกใช้) เมื่อ TokenSave::open ทำงาน — ไม่ว่าจะเป็นคำสั่ง CLI หรือการเริ่ม MCP server — และ branch ที่ใช้งานอยู่ไม่ถูกติดตาม tokensave สามารถติดตามได้ทันทีโดยการคัดลอก DB ของ ancestor ที่ถูกติดตามที่ใกล้ที่สุดและบันทึกลงใน metadata ของ branch ฟีเจอร์นี้ถูกควบคุมโดยฟิลด์คอนฟิก auto_track (ค่าเริ่มต้นคือ false) หรือตัวแปรสภาพแวดล้อม TOKENSAVE_AUTO_TRACK ซึ่งจะแทนที่คอนฟิกในแต่ละการรัน (ค่าใดๆ ก็เปิดใช้งานได้ยกเว้น 0, false, no, off, หรือค่าว่าง) การคัดลอกเป็นการคัดลอก DB จาก ancestor ที่แทบจะทันทีเหมือนกับการรัน branch add ด้วยตนเอง ไม่มีการซิงก์เกิดขึ้นในขณะนั้น — hook post-commit จะทำให้ DB ของ branch ใหม่อยู่เสมอเมื่อคุณ commit หรือรัน tokensave sync เพื่อรีเฟรชทันที การติดตามอัตโนมัติเป็นแบบ best-effort อย่างเคร่งครัด: ความล้มเหลวใดๆ จะถูกรายงานเป็นคำเตือนและ open() จะดำเนินการต่อด้วยการ fallback ไปยัง ancestor ตามปกติ ดังนั้นจึงไม่สามารถทำให้การเรียกใช้เครื่องมือล้มเหลวได้

โดยสรุป: เมื่อติดตั้ง hook แล้ว การ checkout branch ฟีเจอร์ใหม่ — รวมถึง branch ที่ fresh clone หรือ worktree เริ่มต้น — จะได้รับกราฟเฉพาะ branch ของตัวเองอย่างโปร่งใส; เมื่อเปิดใช้งาน auto_track แม้แต่ branch ที่สร้างขึ้นนอกการ checkout ก็จะถูกจับได้ในครั้งแรกที่ tokensave เปิดโปรเจกต์บน branch นั้น

ดูคู่มือฉบับเต็มได้ที่ docs/BRANCHING-USER-GUIDE.md

หน่วยความจำข้ามเซสชัน

เครื่องมือ MCP สามตัวจัดเก็บการตัดสินใจและบริบทพื้นที่โค้ดข้ามเซสชัน โดยเก็บไว้ใน .tokensave/tokensave.db ของแต่ละโปรเจกต์

ใช้เครื่องมือเหล่านี้เพื่อให้ agent ไม่ต้องอธิบายตัวเลือกสถาปัตยกรรมซ้ำในทุกเซสชัน

บัญชีการประหยัด

ทุกการเรียก MCP จะเขียนแถวแบบ append-only ไปยัง ~/.tokensave/global.db (ตาราง savings_ledger) ตรวจสอบด้วย tokensave gain:

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

การประมาณค่าเป็นดอลลาร์ใช้โมดูลการกำหนดราคาที่มีอยู่ (ราคา input ของ Sonnet รีเฟรชทุกวันผ่าน LiteLLM)

เกณฑ์มาตรฐานที่ทำซ้ำได้

tokensave bench รันชุดคำสั่งค้นหาที่กำหนดผ่าน tokensave_context และรายงานการประหยัดการดึงข้อมูลเทียบกับ baseline แบบเต็มไฟล์ (สะท้อนวิธีการของ CCE):

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

วัดกับ repo นี้ (tokensave เอง) โดยใช้ชุดคำสั่งค้นหาทั่วไปที่มาพร้อม:

รวม: การประหยัดการดึงข้อมูลเฉลี่ย 88% (142.8k → 5.5k tokens จากการค้นหา 10 ครั้ง)

ชุดคำสั่งค้นหาเริ่มต้นกำหนดเป้าหมายรูปแบบที่พบในโค้ดเบสแอปพลิเคชันส่วนใหญ่ (CLIs, daemons, services) รันบนโปรเจกต์ของคุณเองด้วย tokensave bench เพื่อดูตัวเลขของคุณ หรือเขียนไฟล์คำสั่งค้นหาที่ปรับแต่ง (--queries my.toml) เพื่อการเรียกคืนที่แม่นยำยิ่งขึ้น

เกณฑ์มาตรฐาน Criterion กับ repo โลกจริงขนาดใหญ่

benches/large_repos.rs เป็น micro-benchmark แบบ criterion ที่ทดสอบเครื่องมือ MCP แบบ end-to-end กับโค้ดเบสโอเพนซอร์สขนาดใหญ่สี่ตัวที่ปักหมุดที่ ref คงที่ แต่ละเครื่องมือถูกขับเคลื่อนด้วย อย่างน้อย 5 คำสั่งค้นหา พร้อมอาร์กิวเมนต์ (node ids, qualified names, file globs, …) ที่สุ่มจากกราฟที่จัดทำดัชนีครั้งเดียวต่อ repo ดังนั้นเวลาจึงทำซ้ำได้ข้ามการรัน

Repos และ refs ที่ปักหมุด (นิยามใน benches/repos.rs):

แต่ละ repo ถูก shallow-clone (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) ในการใช้ครั้งแรกและแคชในเครื่อง; การรันครั้งต่อไปจะใช้ checkout เดิม เอาต์พุต Git ถูกสตรีมไปยังเทอร์มินัลเพื่อให้การดึงข้อมูลหลาย GB แสดงความคืบหน้าแบบเรียลไทม์

เครื่องมือที่ครอบคลุม (5 คำสั่งค้นหาต่อเครื่องมือ) เครื่องมืออ่าน — search, context, callers, callees, node, by_qualified_name, signature, impact, body, files, complexity, doc_coverage, largest, hotspots, god_class, module_api, derives, dead_code, rank, coupling, circular. เครื่องมือเขียน — str_replace, multi_str_replace, insert_at, และ (ถ้า ast-grep เปิดอยู่บน PATH) ast_grep_rewrite

Force-sync ทุกการรัน ก่อนที่ benchmark ใดจะเริ่ม harness จะรันเทียบเท่ากับ tokensave sync --force บนแต่ละ repo (index_all() โดยไม่คำนึงถึงความสดของ .tokensave/) เพื่อให้เวลาสะท้อนซอร์สที่ปักหมุดเสมอ

Write benches และการทำความสะอาด เครื่องมือเขียนแก้ไขไฟล์ เพื่อให้เงื่อนไข "match ต้องไม่ซ้ำกัน" ยังคงอยู่ harness ใช้ iter_batched ของ criterion — ไฟล์ scratch ขนาดเล็กภายใต้ <repo>/.tokensave-bench-scratch/ ถูกเขียนใหม่ด้วยเนื้อหาที่รู้จัก ก่อนทุก iteration ที่จับเวลา จากนั้นเครื่องมือแก้ไขจะรันกับไฟล์นั้น หลังจาก benchmark ทั้งหมดเสร็จสิ้น harness จะรัน git stash --include-untracked && git stash drop ภายในทุก repo ที่เตรียมไว้เพื่อให้ working tree กลับไปที่ ref ที่ปักหมุด

การกำหนดค่า Criterion bench แทนที่ค่าเริ่มต้นของ criterion เป็น sample_size = 10 และ measurement_time = 30s (เทียบกับ 100 / 5s มาตรฐาน) ซึ่งให้เวลาการวัด ~30 วินาทีต่อคำสั่งค้นหา — เพียงพอสำหรับเครื่องมือที่ช้าเช่น tokensave_context บน polkadot-sdk เพื่อสร้างตัวเลขที่เสถียร

รัน:

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

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

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

cargo bench --bench large_repos

ถ้า TOKENSAVE_BENCH_REPOS_DIR ไม่ถูกตั้งค่า bench จะพิมพ์ประกาศและลงทะเบียน benchmark เป็นศูนย์ (เพื่อให้ cargo bench --all ยังคงมีต้นทุนต่ำบนเครื่องของผู้มีส่วนร่วม)

การกำหนดค่า (ทั้งหมดไม่บังคับ ผ่านสภาพแวดล้อม):

การกรอง benchmarks ใช้ CLI มาตรฐานของ criterion — ตัวอย่างเช่น เฉพาะเครื่องมือ search บน scipy:

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

รายงาน (HTML + ตัวอย่างดิบ) อยู่ภายใต้ target/criterion/

ในการเปลี่ยน refs ที่ปักหมุด (เช่น เป็น release ใหม่หรือ SHA เฉพาะ) แก้ไข REPOS ใน benches/repos.rs และลบเครื่องหมาย $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref ที่เกี่ยวข้องเพื่อให้การรันครั้งถัดไปดึงข้อมูลใหม่ ถ้าคุณข้ามการทำความสะอาดหลังรัน (เช่น คุณ Ctrl-C กลาง bench) รัน git stash --include-untracked && git stash drop ภายในไดเรกทอรี repo แต่ละอันเพื่อกู้คืนด้วยตนเอง

MCP test-matrix probe (scripts/mcp_probe)

scripts/mcp_probe/ เป็น harness Python ที่ขับเคลื่อน tokensave serve ผ่าน stdio กับชุด repo จริงที่กำหนดค่าได้และทดสอบ ทุกเครื่องมือ MCP แบบอ่านอย่างเดียวด้วย 5 รูปแบบคำสั่งค้นหาต่อภาษา สร้างตารางสถานะต่อเครื่องมือ / ต่อ repo harness เดียวกันใช้เพื่อสองวัตถุประสงค์:

• การกวาดล้างการถดถอย การสนับสนุนภาษาใหม่ เครื่องมือใหม่ หรือการรีแฟกเตอร์ — รันเมทริกซ์อีกครั้งและเซลล์ใดๆ ที่ผิดพลาดใหม่ หมดเวลา หรือคืนผลลัพธ์ว่างจะโดดเด่นเป็น 🚩
• การตรวจสอบประสิทธิภาพ เวลาต่อการเรียกถูกบันทึกใน TSV; กลุ่ม repo คงที่เดียวกันใช้เป็น การเปรียบเทียบข้ามเวอร์ชันคร่าวๆ วงจรบั๊ก tokensave_inheritance_depth ปัจจุบันถูกพบโดย harness นี้เมื่อเครื่องมือเดียวบน polkadot-sdk หมดเวลาที่ >60 วินาที

โครงสร้าง — probe.py เป็นไดรเวอร์ (JSON-RPC ที่จับคู่ id เพื่อให้เครื่องมือที่ช้าไม่สามารถปนเปื้อนการเรียกถัดไป) isolated.py รันเครื่องมือเดียวซ้ำด้วย server ใหม่ต่อการเรียก (หลีกเลี่ยงการเข้าคิวของ server) build_matrix.py อ่าน TSV และสร้าง markdown tools/<lang>.py โมดูลมีส่วนร่วมในชุดคำสั่งค้นหาต่อภาษา (Rust มาพร้อม; เพิ่ม Python/Go/… โดยวางโมดูลใหม่) repos.toml ระบุ repo เป้าหมาย (แทนที่ผ่าน $TOKENSAVE_PROBE_REPOS)

รันด่วน:

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

เซลล์เอาต์พุตคือ ✓ 5/5 (สะอาด) 🐛 e/N (ข้อผิดพลาด) ⏱ N/N (หมดเวลา) ∅ E/N (ว่าง) 🐢 ok/slow (การเรียก >10 วินาที) เซลล์ใดๆ ที่มีข้อผิดพลาดหรือหมดเวลาจะได้ 🚩 ในคอลัมน์ขวาสุด รายละเอียดต่อการเรียกพร้อม 100 ตัวอักษรแรกของแต่ละข้อผิดพลาดลงในบันทึก TSV สำหรับการติดตามผล

แตกต่างจาก criterion bench ข้างต้น: criterion วัดความหน่วงต่อ iteration สำหรับชุดเครื่องมือที่โฟกัสบน refs ที่ปักหมุดและสร้างรายงานทางสถิติภายใต้ target/criterion/; mcp_probe ทดสอบทุกเครื่องมือด้วยชุดคำสั่งค้นหาที่กว้างขึ้นบน repo ใดๆ ที่คุณชี้ไป เพิ่มประสิทธิภาพเพื่อความครอบคลุมที่กว้างมากกว่าความแม่นยำในการวัด

เครื่องมือ MCP มากกว่า 80 รายการ

server เปิดเผยเครื่องมือมากกว่า 80 รายการ (น้อยกว่าหนึ่งรายการเมื่อไบนารี ast-grep ที่ไม่บังคับไม่ได้อยู่บน PATH); ตารางด้านล่างจัดกลุ่มเครื่องมือที่ใช้บ่อยที่สุดตามหมวดหมู่ ส่วนใหญ่เป็นแบบอ่านอย่างเดียว ปลอดภัยที่จะเรียกแบบขนาน และมีคำอธิบายประกอบด้วย readOnlyHint primitives การแก้ไขถูกจำกัดขอบเขตเป็นไฟล์เดียวและจัดทำดัชนีใหม่ในที่; เครื่องมือบันทึก baseline เซสชันและหน่วยความจำยังแก้ไขสถานะ .tokensave ในเครื่องและถูกระบุว่าไม่ใช่แบบอ่านอย่างเดียว เครื่องมือหลักสามตัว (tokensave_context, tokensave_search, tokensave_status) ถูกทำเครื่องหมายเป็น anthropic/alwaysLoad เพื่อให้ข้ามการค้นหาแบบไปกลับของเครื่องมือของไคลเอนต์

ค้นหาโปรเจกต์อื่นที่เริ่มต้นแล้ว

เครื่องมืออ่านเชิงความหมายสามารถค้นหากราฟในเครื่องที่เลือกอย่างชัดเจนโดยไม่ต้องรีสตาร์ท MCP server:

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

ผลลัพธ์ที่เลือกมี provenance ราก/branch ตามบัญญัติ Node IDs ถูก namespaced ไปยังกราฟนั้น และ selectors ที่ตรงกันต้องถูกทำซ้ำในการเรียกติดตามผล ตัวอย่างเช่น การติดตามผลของการค้นหาที่เลือก branch รวมทั้งสองค่า:

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

graph_root ต้องเป็นรากสัมบูรณ์ที่แน่นอนของโปรเจกต์ที่เริ่มต้นแล้ว graph_branch ไม่บังคับ และเมื่อระบุ ต้องตั้งชื่อ branch ที่ถูกติดตาม การเปิดที่เลือกเป็นแบบอ่านอย่างเดียว: ไม่เคยเริ่มต้น ซิงก์ ย้ายข้อมูล ติดตามอัตโนมัติ หรือเขียนข้อมูลกราฟ/ซอร์ส และไม่นับรวมในการบัญชีการประหยัด การเรียกโดยไม่มี selectors ทำงานเหมือนเดิมทุกประการ graph_root จะมีประโยชน์ก็ต่อเมื่อคุณรู้ว่าโปรเจกต์อื่นมีอยู่จริง ดังนั้นเซิร์ฟเวอร์จึงแจ้งให้คุณทราบ: โปรเจกต์ที่เริ่มต้นแล้วซึ่งอยู่ติดกับรูทที่ให้บริการโดยตรงจะถูกระบุชื่อใน MCP instructions, ใน tokensave_status, และในผลลัพธ์ tokensave_search / tokensave_context ที่ว่างเปล่า — ซึ่งเป็นจุดที่เซสชันจะสรุปว่าสัญลักษณ์ไม่มีอยู่จริงแทนที่จะมองไปที่โปรเจกต์ข้างเคียง (#375) มีเพียงโปรเจกต์พี่น้องที่อยู่ติดกันเท่านั้นที่จะถูกเสนอให้ สูงสุดห้าโปรเจกต์ และจะไม่มีการเปิดหรือจัดทำดัชนีใดๆ ในนามของโปรเจกต์เหล่านั้น การค้นหาโปรเจกต์ใดโปรเจกต์หนึ่งยังคงต้องใช้ graph_root อย่างชัดเจน

ตัวเลือก (selectors) ถูกทำให้ไม่สามารถใช้ได้โดยเจตนากับเครื่องมือที่เขียนข้อมูล, เรียกใช้คำสั่งภายนอก, หรือขึ้นอยู่กับ checkout ปัจจุบัน: พริมิตีฟการแก้ไข, เครื่องมือ VCS และ branch, การวินิจฉัยและการรันทดสอบ, การตรวจสอบ dependency และ runtime, เครื่องมือ workflow และ session-memory, เครื่องมือ persistent-cache (tokensave_redundancy), และการดูแลเซิร์ฟเวอร์ เครื่องมือเหล่านั้นจะปฏิเสธตัวเลือกแทนที่จะเพิกเฉยอย่างเงียบๆ

การค้นพบ

อาร์ติแฟกต์ที่ไม่ใช่โค้ด

tokensave_files ครอบคลุมมากกว่าซอร์สโค้ด ไฟล์ที่มีนามสกุลอยู่ใน artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md โดยค่าเริ่มต้น) จะถูกติดตามตามเส้นทาง เพื่อให้คำถามเช่น "ไฟล์ .feature สำหรับโฟลว์การเข้าสู่ระบบอยู่ที่ไหน?" มีคำตอบเป็นกราฟแทนที่จะถูกบล็อกด้วย find (#323) ไฟล์เหล่านี้ไม่ถูกแยกวิเคราะห์และไม่ให้สัญลักษณ์ใดๆ; kind: "artifact" และ kind: "code" กรองระหว่างสองสิ่งนี้ และการวิเคราะห์ที่หมายถึง "โค้ด" จะแยกไฟล์เหล่านี้ออก นามสกุลที่ตัวแยกภาษาจัดการอยู่แล้วจะถูกละเว้นในรายการนี้ ดังนั้นจึงไม่สามารถใช้เพื่อหยุดการแยกวิเคราะห์ภาษาได้

รายการนี้ยังตัดสินใจว่า การค้นหาแบบ literal สามารถมองเข้าไปในไฟล์ใดได้ (#442) การค้นหาแบบ literal (literal: true) เหนือ tokensave_search อ่านไบต์แทนที่จะเป็นสัญลักษณ์ ดังนั้นจึงไม่ต้องใช้ parser -- แต่จะวนซ้ำไฟล์ที่ถูกจัดทำดัชนี ดังนั้นจึงเข้าถึงได้เฉพาะไฟล์ที่ดัชนีมีแถวข้อมูลอยู่เท่านั้น เทมเพลต .html หรือสไตล์ชีต .css ที่ถูกติดตามไม่มีทั้ง extractor และรายการอาร์ติแฟกต์เริ่มต้น ดังนั้นการจับคู่จึงหายไป; เพิ่มนามสกุลที่นี่แล้วรัน tokensave sync -f แล้วบรรทัดของมันจะถูกค้นหาเหมือนไฟล์อื่นๆ โดยรายงานด้วย enclosing: null เนื่องจากไม่มีบริบทสัญลักษณ์ การตอบสนองแบบ literal ที่ไม่สามารถเข้าถึงทุกไฟล์ที่ติดตามได้จะระบุไว้ในบล็อก unscanned ที่ระบุจำนวนและนามสกุล ดังนั้นคำตอบบางส่วนจะไม่ถูกนำเสนอเป็นคำตอบที่สมบูรณ์

กราฟการเรียก & ผลกระทบ

คุณภาพโค้ด

การวิเคราะห์สุขภาพโค้ด

เครื่องมือห้าตัวแสดงสัญญาณคุณภาพเชิงโครงสร้างจากกราฟที่มีอยู่ คะแนนรวมใช้ค่าเฉลี่ยเรขาคณิตเหนือมิติอิสระ เพื่อไม่ให้มิติใดมิติหนึ่งถูกเอาเปรียบได้

เซสชัน

บันทึกเมตริกสุขภาพเมื่อเริ่มต้นเซสชันการเขียนโค้ด AI จากนั้นเปรียบเทียบความแตกต่างเมื่อสิ้นสุดเพื่อดูว่าอะไรดีขึ้นหรือแย่ลง

พริมิตีฟการแก้ไข

เครื่องมือเขียนสี่ตัวที่ให้เอเจนต์แก้ไขไฟล์โดยไม่มีความเสี่ยงจาก regex หรือ shell-quoting แต่ละตัวเป็นไฟล์เดียว, มีจุดยึด, และทริกเกอร์การจัดทำดัชนีใหม่ในตำแหน่งเดิมหลังการเขียน เพื่อให้กราฟไม่เก่า

Git & เวิร์กโฟลว์

ระบบชนิดข้อมูล

การย้ายโค้ด

หลาย Branch

ทรัพยากร MCP

ทรัพยากรสี่รายการถูกเปิดเผยผ่าน resources/list และ resources/read:

• tokensave://status -- สถิติกราฟเป็น JSON
• tokensave://files -- ต้นไม้ไฟล์ที่ถูกจัดทำดัชนีจัดกลุ่มตามไดเรกทอรี
• tokensave://overview -- สรุปโปรเจกต์พร้อมการกระจายภาษาและชนิดสัญลักษณ์
• tokensave://branches -- branches ที่ถูกติดตามพร้อมขนาด DB และข้อมูล parent

การติดตามโทเค็น

tokensave วัดโทเค็นที่ประหยัดได้ในการเรียกเครื่องมือ MCP ทุกครั้ง การตอบสนองของเครื่องมือแต่ละรายการรวมบรรทัด tokensave_metrics: before=N after=M ที่แสดงจำนวนโทเค็นไฟล์ดิบที่หลีกเลี่ยงได้จากการเรียกเฉพาะนั้น

การปิดการรายงาน บรรทัดเมตริก พร้อมกับประโยคใน MCP instructions, ขอให้เอเจนต์รายงานการประหยัดให้คุณ — ซึ่งหมายความว่าโมเดลใช้โทเค็น เอาต์พุต เพื่อเล่าเรื่องการประหยัดที่ tokensave ทำกับโทเค็น อินพุต โทเค็นเอาต์พุตเป็นชนิดที่แพงกว่า ดังนั้นหากเอเจนต์ของคุณพูดถึง tokensave เกือบทุกเทิร์น การเล่าเรื่องนั้นอาจหักล้างผลประโยชน์ได้ (#356) ตั้งค่า report_savings เป็น false ใน .tokensave/config.json, หรือตัวแปรสภาพแวดล้อม TOKENSAVE_REPORT_SAVINGS เพื่อแทนที่ต่อการรัน (ค่าใดๆ เปิดใช้งานยกเว้น 0, false, no, off, หรือค่าว่าง) ทั้งบรรทัดเมตริกและคำสั่งจะหายไป; tokensave install หยุดการเขียนกฎการรายงานลงในไฟล์พรอมต์เอเจนต์เช่นกัน การวัดไม่ได้รับผลกระทบไม่ว่ากรณีใด — ทุกการเรียกยังคงลงในบัญชีการประหยัด ดังนั้น tokensave gain, tokensave list, status และ monitor ยังคงรายงานเหมือนเดิม ค่าเริ่มต้นยังคงเป็น true

การสังเกตต้นทุน

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

แยกวิเคราะห์บันทึกเซสชัน Claude Code (~/.claude/projects/**/*.jsonl), จัดประเภทการเรียก API แต่ละเทิร์นเป็นหนึ่งใน 13 หมวดหมู่งาน, คำนวณต้นทุนเป็นดอลลาร์โดยใช้ราคาโมเดล, และเก็บผลลัพธ์ใน ~/.tokensave/global.db สำหรับการสอบถามรวมที่รวดเร็ว ราคาจะถูกรีเฟรชจาก LiteLLM ทุก 24 ชั่วโมงและสำรองไปยังตารางในตัวเมื่อออฟไลน์

ส่วนหัว tokensave status รวมแถวต้นทุนที่แสดงการใช้จ่ายวันนี้, ยอดรวม 7 วัน, และอัตราส่วนประสิทธิภาพ (โทเค็นที่ประหยัด / โทเค็นทั้งหมด) TUI tokensave monitor แสดงแผงต้นทุนสดควบคู่กับฟีดการประหยัด เมื่อสิ้นสุดเซสชัน Claude Code แต่ละครั้ง ตัวจัดการ hook_stop พิมพ์ใบเสร็จหนึ่งบรรทัดไปยังเทอร์มินัล

หมวดหมู่การจัดประเภทงาน: การเขียนโค้ด, การดีบัก, การพัฒนาฟีเจอร์, การรีแฟกเตอร์, การทดสอบ, การสำรวจ, การวางแผน, การมอบหมายงาน, Git Ops, Build/Deploy, การระดมสมอง, การสนทนา, ทั่วไป การจัดประเภทเป็นแบบกำหนด (การจับคู่รูปแบบกับชื่อเครื่องมือและคำสั่ง Bash), ไม่ต้องใช้การเรียก LLM, และดัดแปลงจาก AgentSeal/codeburn

จอภาพสด

tokensave monitor

TUI ระดับโลกที่แสดงการเรียกเครื่องมือ MCP จากทุกโปรเจกต์แบบเรียลไทม์ ผ่านบัฟเฟอร์วงแหวนหน่วยความจำที่ใช้ร่วมกันที่ ~/.tokensave/monitor.mmap แต่ละรายการแสดงชื่อโปรเจกต์, ชื่อเครื่องมือ, และความแตกต่างของโทเค็น แผงต้นทุนที่ด้านบนแสดงการใช้จ่ายวันนี้, การประหยัด, ประสิทธิภาพ, และโมเดลสูงสุด (รีเฟรชทุก 30 วินาที)

การวินิจฉัยหน่วยความจำ

tokensave memory [--clean]

รายงานหน่วยความจำระดับเครื่องสำหรับทุกโพรเซสของ tokensave (MCP servers, syncs, index runs) ผ่านตารางหน่วยความจำที่แมปแบบใช้ร่วมกันที่ ~/.tokensave/memory.mmap แต่ละอินสแตนซ์สุ่มตัวอย่าง RSS ของตัวเองแบบ best-effort เมื่อเริ่มต้น, ต่อการเรียกใช้เครื่องมือ MCP, และรอบเฟส sync/resolution ดังนั้นรายงานจะแสดง RSS ปัจจุบันและสูงสุด พร้อมกับเฟสที่ทำให้เกิดค่าสูงสุด — ข้อมูลที่จำเป็นสำหรับการระบุสาเหตุของการใช้หน่วยความจำสูง (ดู #253) แถวถูกทำเครื่องหมายด้วย alive, dead (โพรเซสที่ถูก OOM-kill ทิ้งค่าสูงสุด/เฟสไว้เป็นบันทึกทางนิติเวช) หรือ orphan (ยังทำงานอยู่แต่ถูก reparent ไปที่ init) --clean ล้างช่องที่ตายแล้ว

PEAK PHASE ระบุชื่อ ตัวอย่าง ที่สูงที่สุด ดังนั้นจึงแม่นยำเท่ากับการสุ่มตัวอย่างเท่านั้น บันทึกการ sync แบบเพิ่มหน่วย ตามลำดับ: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done การ index แบบเต็มบันทึก index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done

แต่ละรายการถูกบันทึกหลังจากงานที่มันระบุชื่อเสร็จสิ้น เดิมทีบันทึกก่อนหน้านั้น ดังนั้นทุกตัวอย่างรายงาน RSS ของขั้นตอนก่อนหน้าภายใต้ป้ายชื่อของขั้นตอนถัดไป — ซึ่งทำให้ระบุ 73 MiB ไปที่การโหลดโหนดซึ่งจริงๆ แล้วเป็นของการโหลด unresolved references ซึ่งเป็นขั้นตอนที่ไม่มีตัวอย่างเลย และชี้การตรวจสอบหน่วยความจำไปที่ระบบย่อยที่ผิดเป็นเวลาหลายเดือน (#409) หากคุณเพิ่มเฟส ให้สุ่มตัวอย่างหลังจากงาน ไม่ใช่ก่อนหน้า และเพิ่มหนึ่งเฟสสำหรับขั้นตอนใดๆ ที่ใหญ่พอที่จะเก็บค่าสูงสุด

เซสชันและตัวนับตลอดอายุการใช้งาน

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

tokensave status แสดงสถิติดัชนีโปรเจกต์, การแบ่งตามภาษา, แถวต้นทุน (วันนี้ / 7 วัน / ประสิทธิภาพ) และยอดรวมตลอดอายุการใช้งานของโปรเจกต์และทั่วโลก:

ตัวนับทั่วโลก

ผู้ใช้ tokensave ทุกคนมีส่วนร่วมในตัวนับรวมแบบไม่ระบุตัวตน tokensave status แสดงทั้งยอดรวมโปรเจกต์ของคุณและยอดรวมทั่วโลก การอัปโหลดส่งเพียงตัวเลขเดียว (เช่น 4823) โดยไม่มีข้อมูลระบุตัวตน เลือกไม่ใช้ด้วย tokensave disable-upload-counter

ความสดของดัชนี

tokensave ทำให้กราฟเป็นปัจจุบันโดยไม่ต้องมี daemon พื้นหลังหรือตัวเฝ้าดูไฟล์ระดับ OS

การตรวจสอบความเก่าตามความต้องการ ทุกการเรียกใช้เครื่องมือ MCP จะตรวจสอบว่าไฟล์ที่ถูก index ถูกแก้ไขตั้งแต่การ sync ครั้งล่าสุดหรือไม่ หากพบไฟล์ที่เก่า ไฟล์เหล่านั้นจะถูก extract ใหม่ก่อนที่จะส่งคืนการตอบสนองของเครื่องมือ การหน่วงเวลา 30 วินาทีป้องกันการเรียกติดต่อกันไม่ให้เดินทรีซ้ำทุกครั้งที่กดแป้น

Catch-up sync เมื่อเชื่อมต่อ เมื่อ MCP server เริ่มทำงาน มันจะรัน catch-up sync แบบไม่บล็อกทันที ซึ่งเก็บการเปลี่ยนแปลงใดๆ ที่เกิดขึ้นในขณะที่ไม่มี agent แนบอยู่ — เช่น git pull, การแก้ไขใน IDE, ขั้นตอน build — ดังนั้นการเรียกใช้เครื่องมือครั้งแรกของเซสชันจะเห็นดัชนีที่สดใหม่

การทำงานแบบหลาย agent และ git worktrees เมื่อหลาย agent ทำงานในโปรเจกต์เดียวกันพร้อมกัน ข้อสมมติหลักคือแต่ละ agent ทำงานใน git worktree ของตัวเอง Worktrees คือการ checkout ระบบไฟล์อิสระของ repository เดียวกัน: agent A และ agent B ต่างมีสำเนาของทุกไฟล์เป็นของตัวเอง ดังนั้นพวกเขาจะไม่เขียนทับการแก้ไขที่กำลังทำของกันและกัน tokensave ตรวจจับโดยอัตโนมัติเมื่อคำสั่งมาจาก worktree ที่ซ้อนอยู่ภายใน main checkout และให้ผลลัพธ์จากกราฟสาขาที่ถูกต้อง การเปลี่ยนแปลงสะสมอย่างอิสระและในที่สุดจะถูกกระทบยอดผ่าน git merge หรือ rebase — กระบวนการเดียวกับที่ใช้สำหรับการพัฒนาคู่ขนานอื่นๆ การออกแบบนี้หลีกเลี่ยงความซับซ้อนและโหมดความล้มเหลวของการล็อกข้าม agent บนไดเรกทอรีที่ใช้ร่วมกันซึ่งแก้ไขได้

เวิร์กโฟลว์ CLI เท่านั้น หากคุณรันคำสั่ง tokensave โดยไม่มี agent แนบอยู่ (ไม่มี MCP server) การตรวจสอบความเก่าจะไม่ทำงานระหว่างคำสั่ง ติดตั้ง git hooks เพื่อให้ดัชนีสดใหม่อย่างอัตโนมัติหลังทุก commit หรือ clone:

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

อัปเกรดจาก 5.x

คำสั่ง tokensave daemon แบบสแตนด์อโลนและการ autostart ผ่าน launchd/systemd/Windows Service ถูกลบออกใน 6.0.0 ตัวเฝ้าดูไฟล์ระดับ OS ที่ฝังตัวซึ่งแทนที่ daemon ถูกถอดออกใน 6.1.1 (ทำให้ CPU และหน่วยความจำทำงานหนักเกินไปบน monorepo ขนาดใหญ่ที่มีทรี node_modules หรือ target ลึก) โมเดลการตรวจสอบความเก่าตามความต้องการข้างต้นคือการออกแบบปัจจุบัน

หากคุณยังมี daemon autostart จาก 5.x ให้ลบออก:

• macOS: launchctl unload ~/Library/LaunchAgents/com.tokensave.daemon.plist && rm ~/Library/LaunchAgents/com.tokensave.daemon.plist
• Linux: systemctl --user disable --now tokensave-daemon && rm ~/.config/systemd/user/tokensave-daemon.service
• Windows: sc.exe delete tokensave-daemon (จากเทอร์มินัลที่ยกระดับสิทธิ์)

หากคุณจำชื่อที่แน่นอนไม่ได้: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave

การอัปเกรดตัวเอง

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

tokensave upgrade ดาวน์โหลดไบนารีแพลตฟอร์มที่ถูกต้องจาก GitHub releases และแทนที่ไบนารีที่กำลังทำงานในตำแหน่งเดิม รองรับช่องทาง stable และ beta อย่างอิสระ

เวอร์ชันและการอัปเกรด

หมายเลขเวอร์ชันของ tokensave ดูเหมือน SemVer แต่ ไม่ปฏิบัติตาม: คอมโพเนนต์ที่เปลี่ยนแปลงจะเข้ารหัสการบำรุงรักษาที่การอัปเดตต้องการ ซึ่ง tokensave ดำเนินการโดยอัตโนมัติในการเปิดตัวครั้งถัดไป — คุณไม่ต้องรันการติดตั้งใหม่หรือ reindex ด้วยตนเอง

การติดตั้งใหม่ทั่วโลก ในการรันครั้งแรกของ build minor หรือ major ใหม่ tokensave รัน install ใหม่สำหรับแต่ละ agent ที่ลงทะเบียนอย่างเงียบๆ เพื่อให้ agent config ชี้ไปที่ไบนารีปัจจุบันและเปิดเผยชุดเครื่องมือปัจจุบันเสมอ Patch bumps ข้ามขั้นตอนนี้ — เพียงแค่เลื่อนเครื่องหมายเวอร์ชันที่ทำงานอยู่

การติดตั้งใหม่เงียบจริงๆ: ผลลัพธ์การตั้งค่าต่อ agent ที่คุณเห็นจากการรัน tokensave install อย่างชัดเจนถูกระงับที่นี่ ดังนั้นมันจะไม่ปรากฏต่อหน้าคำสั่ง tokensave init หรือ tokensave sync ทั่วไป หากไม่สามารถรีเฟรช config ของ agent ได้ — แอปไม่ได้ติดตั้ง หรือ config อยู่ในตำแหน่งที่อ่านอย่างเดียว — คุณจะเห็นหนึ่งบรรทัดที่ระบุชื่อ agent ที่ล้มเหลว:

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

รัน tokensave install เพื่อดูข้อผิดพลาดพื้นฐาน เครื่องหมายเวอร์ชันเลื่อนไปทั้งสองทาง ดังนั้นเส้นทาง config ที่ไม่สามารถเขียนได้จะถูกรายงานครั้งเดียวต่อการอัปเกรดแทนที่จะลองใหม่ในทุกคำสั่งถัดไป

การบังคับ reindex ต่อโปรเจกต์ (major เท่านั้น) การ bump major หมายความว่าดัชนีโปรเจกต์ต้องถูกสร้างใหม่ tokensave ทำสิ่งนี้แบบขี้เกียจและต่อโปรเจกต์: ในการเรียกใช้เครื่องมือ MCP ครั้งแรก ในโปรเจกต์หลังการอัปเกรด major มันจะสร้าง full reindex พื้นหลัง (เทียบเท่า tokensave sync --force) ซึ่งไม่บล็อกการตอบสนองของเครื่องมือ

Brew / cargo fallback การอัปเกรดภายนอกที่แทนที่ไบนารีนอกเหนือจาก tokensave upgrade — เช่น brew upgrade tokensave หรือ cargo install tokensave — ถูกตรวจจับในลักษณะเดียวกัน: หากเวอร์ชันที่ทำงานใหม่กว่าเวอร์ชันสุดท้ายที่ทำการติดตั้ง การติดตั้งใหม่จะรันในการเปิดตัวครั้งถัดไปเช่นเดียวกับหลังการอัปเกรดตัวเอง

ดู TOKENSAVE-VERSIONING.md สำหรับเหตุผลที่ tokensave เบี่ยงเบนจาก SemVer (การเข้ารหัสการบำรุงรักษาในเวอร์ชันคือสิ่งที่ทำให้การอัปเกรดแบบไม่ต้องสัมผัสเป็นไปได้), กลไกเครื่องหมาย, เวอร์ชัน schema ฐานข้อมูลอิสระ และกฎสำหรับผู้ดูแลในการตัด releases

ข้อมูลอ้างอิง CLI

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

tokensave doctor

รันการตรวจสอบสุขภาพที่ครอบคลุมของการติดตั้ง tokensave ของคุณ:

tokensave doctor

การตรวจสอบ: ตำแหน่งไบนารี, ดัชนีโปรเจกต์, ฐานข้อมูลทั่วโลก, user config, agent integration (MCP server, hooks, สิทธิ์, กฎ prompt) และการเชื่อมต่อเครือข่าย หากสิทธิ์เครื่องมือใดหายไปหลังการอัปเกรด มันจะบอกให้คุณรัน tokensave install ใช้ --agent เพื่อตรวจสอบเฉพาะ agent ที่ระบุ

Doctor ยังตรวจสอบว่าแต่ละ hook ที่ติดตั้งใช้คำสั่งย่อย tokensave ที่ถูกต้องและซ่อมแซม hooks ที่เสียหายโดยอัตโนมัติ

วิธีการทำงานกับ Claude Code

เมื่อกำหนดค่าแล้ว Claude Code จะใช้ tokensave โดยอัตโนมัติแทนการอ่านไฟล์ดิบเมื่อต้องการทำความเข้าใจ codebase ของคุณ สามชั้นเสริมซึ่งกันและกัน:

ผลลัพธ์: Claude เข้าใจโค้ดเดียวกันด้วย token น้อยลงมาก Explore agent ทั่วไปอ่านไฟล์ 20-50 ไฟล์; tokensave ส่งคืนสัญลักษณ์, ความสัมพันธ์ และตัวอย่างโค้ดที่เกี่ยวข้องจากดัชนีที่สร้างไว้ล่วงหน้า

การเรียกเครือข่ายและความเป็นส่วนตัว

ฟังก์ชันหลักของ tokensave (indexing, search, graph queries, MCP server) เป็น ท้องถิ่น 100% — โค้ดของคุณไม่เคยออกจากเครื่องของคุณ

การอัปโหลดตัวนับทั่วโลกส่ง HTTP POST เดียวพร้อม body JSON เช่น {"amount": 4823} ไม่มีคุกกี้, ไม่มีการติดตาม, ไม่มี ID ผู้ใช้ Cloudflare Worker บันทึกประเทศของที่อยู่ IP ของคุณ (ได้จาก request headers) สำหรับสถิติทางภูมิศาสตร์รวม — ที่อยู่ IP จริงของคุณไม่ถูกเก็บ

การรีเฟรชราคาโมเดลดึงไฟล์ JSON สาธารณะจาก GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) เพื่อให้ราคาโมเดล Claude เป็นปัจจุบันสำหรับ tokensave cost ไม่มีการส่งข้อมูล — เป็น HTTPS GET ธรรมดา การตอบสนองถูกแคชที่ ~/.tokensave/pricing.json เป็นเวลา 24 ชั่วโมง หากการดึงล้มเหลว tokensave ใช้ตารางราคาที่คอมไพล์ไว้

50+ ภาษา

tokensave รองรับภาษาการเขียนโปรแกรมมากกว่า 50 ภาษาจัดเป็นสามชั้นที่ควบคุมโดย Cargo feature flags แต่ละชั้นรวมทุกภาษาจากชั้นด้านล่าง หัวข้อ Markdown ถูก extract เป็นโหนด Module พร้อมขอบ Contains แบบลำดับชั้น เพื่อให้โครงสร้างเอกสารมีส่วนร่วมในการสอบถามกราฟควบคู่กับซอร์สโค้ด

Lite -- --no-default-features

คอมไพล์เสมอ ไบนารีที่เล็กที่สุดสำหรับภาษายอดนิยมที่สุด บวก Svelte และ Astro (การ extract บล็อกสคริปต์ผ่าน TypeScript extractor, ไม่ต้องมี grammar dependency เพิ่มเติม)

Medium (Lite + 9 เพิ่มเติม) -- --features medium

Full (Medium + ทุกอย่างอื่น ๆ) -- ค่าเริ่มต้น

ภาษาต่าง ๆ ยังสามารถเลือกใช้แบบเฉพาะเจาะจงได้โดยไม่ต้องใช้ทั้ง tier:

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

ตัวแยกข้อมูลทั้งหมดใช้ความลึกเดียวกัน: ฟังก์ชัน, คลาส, เมธอด, ฟิลด์, imports, call graphs, inheritance chains, docstrings, complexity metrics, การแยก decorator/annotation, และการติดตาม dependency ข้ามไฟล์

tokensave เทียบกับ CodeGraph

tokensave คือการเขียนใหม่ด้วย Rust ตั้งแต่ต้นของ CodeGraph (Node.js/TypeScript) ทั้งคู่สร้าง semantic code graphs สำหรับ AI coding agents แต่มีความแตกต่างอย่างมีนัยสำคัญในขอบเขตและความสามารถ

CodeGraph เป็นผู้บุกเบิกแนวทางนี้และยังคงเป็นตัวเลือกที่ดีหากคุณชอบเครื่องมือ npm และต้องการเพียงการผสานกับ Claude Code tokensave ขยายแนวคิดด้วยการวิเคราะห์ที่ลึกกว่า, agents มากกว่า, การรองรับ multi-branch, และ native binary ที่ไม่ต้องพึ่งพา runtime ใด ๆ

สำหรับการเปรียบเทียบโดยละเอียดกับ CodeGraph, Dual-Graph (GrapeRoot), code-review-graph, และ OpenWolf ดูได้ที่ docs/COMPARABLE-TOOLS.md

ทำไมต้องเลือก tokensave แทนทางเลือกอื่น

เครื่องมือหลายตัวลดการใช้ token สำหรับ AI coding agents นี่คือเหตุผลที่ tokensave โดดเด่น

Native binary เดียว, ไม่มีการพึ่งพาใด ๆ

ทุกทางเลือกต้องใช้ runtime: Python, Node.js, หรือทั้งคู่ tokensave จัดส่งเป็น Rust binary ขนาด ~25 MB เดียวพร้อม tree-sitter grammars ทั้งหมด 50+ ที่รวมอยู่ในตัว ไม่ต้องติดตั้งอะไรเพิ่มเติม

ความฉลาดในการวิเคราะห์โค้ดที่ลึกที่สุด

tokensave ทำงานที่ระดับ symbol: ฟังก์ชัน, structs, ฟิลด์, call edges, type hierarchies, complexity metrics ทางเลือกอย่าง Dual-Graph (GrapeRoot) ทำงานที่ระดับไฟล์ -- พวกมันรู้ว่าไฟล์ใดมีอยู่แต่ไม่สามารถตอบได้ว่า "ใครเรียกฟังก์ชันนี้?" หรือ "อะไรจะพังถ้าฉันเปลี่ยน struct นี้?" MCP tools เฉพาะทางมากกว่า 80 รายการของ tokensave ครอบคลุม call graph traversal, impact analysis, dead code detection, test mapping, rename preview, type hierarchies, circular dependency detection, complexity ranking, code-health analytics (Gini, DSM, dependency depth, risk-weighted test gaps), atomic edit primitives, และอื่น ๆ คู่แข่งที่ใกล้เคียงที่สุด (code-review-graph) มี 22 tools; ตัวอื่นมี 5-9

การรองรับ agents ที่กว้างที่สุด

การผสานกับ AI coding agents มากกว่าหนึ่งโหลพร้อมรูปแบบการกำหนดค่า native ต่อ agent ไม่มีเครื่องมืออื่นใดครอบคลุม agents จำนวนมากได้ด้วยการผสานที่ลึกเท่านี้ Claude Code ได้รับ hooks, prompt rules, และ auto-allowed tool permissions Kiro ได้รับ global MCP config, tokensave.md steering โหลดเป็น resource, managed agent พร้อมการอนุมัติเครื่องมือ built-in/tokensave ที่ยืดหยุ่น, และ hooks สำหรับ delegation guardrails พร้อม post-write sync agents อื่น ๆ ได้รับการลงทะเบียน MCP server ในรูปแบบการกำหนดค่า native ของตน

Multi-branch indexing

เครื่องมือเดียวในพื้นที่นี้ที่มี per-branch graph databases และ cross-branch diff และ search เมื่อเปิดใช้งาน การสลับ branch ทำได้ทันที -- ไม่ต้อง re-indexing

Per-call token tracking

เครื่องมือเดียวที่รายงานอย่างแม่นยำว่าแต่ละ MCP tool call ประหยัด token ได้กี่ token พร้อม live TUI monitor ครอบคลุมทุกโปรเจกต์และ lifetime counters

โอเพนซอร์สเต็มรูปแบบ

Rust ที่ใช้สัญญาอนุญาต MIT, ตรวจสอบได้ตั้งแต่ต้นจนจบ เครื่องยนต์หลักของ Dual-Graph (graperoot บน PyPI) เป็น proprietary -- คุณไม่สามารถเห็นว่ามันทำอะไรกับ code graph ของคุณ OpenWolf ใช้ AGPL-3.0 ซึ่งกำหนดให้งานลอกเลียนต้องเปิดเป็นโอเพนซอร์ส

ประสิทธิภาพ

การวัดประสิทธิภาพ full-index บน codebase ผสม Rust/Java/Scala จำนวน 1,782 ไฟล์ (57K nodes, 103K edges):

การแก้ไขปัญหา

"tokensave not initialized"

ไดเรกทอรี .tokensave/ ไม่มีอยู่ในโปรเจกต์ของคุณ

tokensave init

MCP server ไม่เชื่อมต่อ

AI agent ไม่เห็นเครื่องมือของ tokensave

1. ตรวจสอบว่า agent config รวม MCP server ของ tokensave (รัน tokensave doctor)
2. รีสตาร์ท agent ทั้งหมด
3. ตรวจสอบว่า tokensave อยู่ใน PATH ของคุณ: which tokensave

สัญลักษณ์หายไปในการค้นหา

• รัน tokensave sync เพื่ออัปเดต index
• ตรวจสอบว่าภาษาได้รับการรองรับ (ดูตารางด้านบน)
• ตรวจสอบว่าไฟล์ไม่ได้ถูกยกเว้นโดย .gitignore

การ indexing ช้า

โปรเจกต์ขนาดใหญ่ใช้เวลานานกว่าในการ full index ครั้งแรก

• การรันครั้งถัดไปใช้ incremental sync และเร็วกว่ามาก
• ใช้ tokensave sync (ไม่ใช่ --force) สำหรับการอัปเดตประจำวัน
• ตรวจสอบ staleness โดยอัตโนมัติในการเรียก MCP tool ทุกครั้งในขณะที่ agent เชื่อมต่ออยู่

การปิดใช้งาน tokensave สำหรับโปรเจกต์เฉพาะ

หากโปรเจกต์ใหญ่เกินไปและ tokensave ใช้ RAM มากเกินไป คุณสามารถปิด MCP server ต่อโปรเจกต์ได้โดยตั้งค่า TOKENSAVE_DISABLE_SERVER=true ใน environment ของมัน server จะออกอย่างสะอาดโดยไม่เริ่มต้น

Claude Code — เพิ่มใน .claude/settings.json ของโปรเจกต์คุณ:

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

agents อื่น ๆ — ตั้งค่า environment variable ใน config ใดก็ตามที่ agent ของคุณใช้เพื่อเปิด MCP servers

คุณยังสามารถตั้งค่าแบบ global ผ่าน shell (TOKENSAVE_DISABLE_SERVER=true claude) แต่จะปิด MCP server ของ tokensave สำหรับทุกโปรเจกต์ใน session

DISABLE_TOKENSAVE=true ยังคงได้รับการรองรับในฐานะ compatibility alias ที่เลิกใช้แล้วสำหรับการกำหนดค่าที่สร้างก่อนที่ตัวแปรนี้จะถูก namespaced

ที่มา

โปรเจกต์นี้เป็น Rust port ของ CodeGraph ต้นฉบับที่เขียนด้วย TypeScript โดย @colbymchenry port นี้รักษาสถาปัตยกรรมเดียวกันและ MCP tool interface ในขณะที่ใช้ประโยชน์จาก Rust เพื่อประสิทธิภาพและ native tree-sitter bindings

การสร้าง

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

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

ประวัติดาว

ผู้สนับสนุน

การลงนามโค้ดฟรีบน Windows จัดทำโดย SignPath.io, ใบรับรองโดย SignPath Foundation

สัญญาอนุญาต

MIT License -- ดู LICENSE สำหรับรายละเอียด

tokensave.dev