vs-token-safer

English · 한국어

A token-saving code layer for Claude Code, for any codebase. TypeScript, JavaScript, and Python work with zero setup; C# and C++ add a language server; and 30+ more languages come in on the built-in tree-sitter tier. Proven up to a 26k-translation-unit Unreal Engine monorepo — so your web, backend, or data repo is the easy case.

Your coding agent has a small context window. Your repo is large. vs-token-safer sits in between.

Ask where something is, what calls it, or even "how does the auth flow work?" when the name escapes you — and instead of pasting a wall of source into the chat, it replies with a short file:line list.

• Builds normally? The answers are exact — it reads the same code index your editor relies on.
• No toolchain set up? It still locates your functions and classes.
• Forgot the name, only remember what it does? It finds it from the vocabulary your own code already uses — no AI model, nothing uploaded.
• Markdown or a config file? Jump straight to one section by its heading instead of opening the whole file.

A companion plugin does the same for giant editor and build logs. None of it leaves your machine.

# Claude tries to grep code → the hook REWRITES it to the indexed query, in place:
$ grep -rn "createSession" src/
↻ [vs-token-safer] Rerouted → search_symbol "createSession"   # semantic, not a text match
  func createSession (in AuthService)  @ src/auth/session.ts:142   (+2 more)
  → ~120 tokens   (grep would have dumped thousands of lines)

# Editing that symbol? Name it — no Read-the-whole-file, no line counting:
$ replace_symbol_body symbol="createSession" body="…"        # preview; apply=true writes
  replace_symbol_body "createSession" — PREVIEW at src/auth/session.ts:142-160

_{Same flow on TypeScript, Python, C#, C++, Go and more (clangd · Roslyn · tsserver · pyright · tree-sitter). VTS_REWRITE=0 blocks instead of rewriting.}

_{The built-in dashboard (vts serve) — your indexed repo as a live 3D graph, all on 127.0.0.1. Three modes: include graph (clangd), call graph (live LSP call hierarchy by symbol), and symbol graph — a tree-sitter map of files + import edges that needs no language server, so it renders on any of the 17 tree-sitter languages with zero setup.}

Why

• Keep the context lean. grep on a large repo — a TypeScript/Python monorepo, a C#/.NET solution, even a 26k-TU Unreal C++ tree — floods the context. The language-server index stays token-capped — ~97–99% smaller (benchmarks).
• Claude keeps reaching for grep. The hook doesn't just block it — it rewrites the command to the indexed query in place, so the search still runs and the flow never breaks.
• Edit by symbol, not by line. Replace/insert-around/delete a declaration by naming it — the index supplies the span, so you skip reading the whole file into context.
• Review a diff by its blast radius, not by eye. detect_changes maps a git diff to the symbols it changed, walks each one's callers, and scores the risk LOW/MED/HIGH — from the blast radius, the caller-cascade depth, and which historically co-changed files this diff left out. A review starts from "what does this actually touch," capped to file:line, nothing uploaded. It's the code-review-context idea done the vs-token-safer way: the official language server for the blast radius and your own git history for the coupling — no persistent graph database, no embeddings.
• You can't tell how much grep still slips through. vts discover reads your recent sessions and reports exactly which searches bypassed the index and what they cost.
• The language server runs headlessly — no editor open, unlike an IDE-proxy approach.

Quickstart

# 1) Install (also auto-installs the gamedev-log-analyzer sibling)
/plugin marketplace add JSungMin/vs-token-safer
/plugin install vs-token-safer@vs-token-safer
/reload-plugins        # first run auto-installs the server deps (no manual npm)

# 2) Configure — detects the backend, asks for the project path, writes the config
/vs-token-safer:setup

Then restart the Claude Code session (the vs-search MCP server only starts on a fresh session). Verify the tools appear and that grep src/**/*.cpp is rerouted to the index. Prerequisites: Node ≥ 18 and a language server — clangd (C/C++) / Roslyn (C#) you install; JS/TS + Python auto-install. Details in Prerequisites below.

Want only the log analyzer? /plugin install gamedev-log-analyzer@vs-token-safer.

How it works

vs-token-safer isn't a search box — it's a precision ladder. You ask where something is, what calls it, or "how does the auth flow work?" when the name escapes you, and it answers at the highest precision it can reach, then tells you which rung the answer came from:

• EXACT — you know the name and the project builds → the official language server (clangd / Roslyn / tsserver / pyright), the semantic ground truth.
• SYNTACTIC — no toolchain set up → a tree-sitter parse (36 grammars bundled, no native build; 19 languages with tuned declaration extraction, the rest via a generic parse) still returns real declarations, not a grep.
• FUZZY — you only remember what the code does → a concept dictionary mined from the repo's own identifiers + comments (no AI model, nothing uploaded).
• SECTION — it's a doc or config, not code → Markdown / TOML / YAML / CSS / HTML addressed by heading.

The rungs aren't a one-time pick — they connect, and vts switches between them as it learns more. Start on FUZZY when you only know the intent; the moment concept_search surfaces a real name, vts climbs to EXACT to confirm it against the semantic index (and an exact search that misses drops back down to FUZZY). The hooks steer that hand-off in both directions, so "I don't know the name" turns into a precise, semantically-verified file:line instead of a dead end.

Graceful degradation — a locate never hard-errors on a cold or missing toolchain. When clangd is missing, cold, or still indexing, a locate degrades to the SYNTACTIC (tree-sitter) tier with a one-line advisory instead of erroring or blocking, then climbs to EXACT once clangd warms. If a committed .vts-index has drifted from the source, the answer is still served but labeled SYNTACTIC · STALE (with a climb: vts index hint). And on a cold locate over a large tree, vts auto-builds the .vts-index/ in the background so the next query (or the same session, once the build finishes) is instant — you never wait on it. So vts index below is best thought of as auto-built in the background; commit it to share, not a manual step you have to remember.

Every answer comes back capped to file:line (never source bodies) and carries a one-line completeness certificate naming the rung — so the model always knows whether it got the semantic truth or a fallback. On a 3-language, 150-file benchmark that's 87% fewer tokens than grep (~138× on a real Unreal Engine 5 tree). Underneath, four mechanisms make Claude actually use the ladder instead of reaching for grep: