Token economy
basemind saves tokens by answering with file paths, line numbers, and signatures — not whole files. A question about your code costs a small fraction of the tokens it takes to read the source.
Why pointers beat file reads
Section titled “Why pointers beat file reads”When you ask “where is the User class defined?”, basemind returns:
src/models/user.ts:42Reading the entire user.ts file would cost 200–2000 tokens, depending on size. The answer costs
just a few tokens.
When you ask “what calls processFile?”, basemind returns 10 call sites with their paths and
line numbers — enough for an agent to decide whether to open each one. Re-reading the whole
calling files would explode your context.
The same discipline applies to every tool: code_outline gives you a file’s structure (signatures,
imports) before you open it, so you read only the span you need. code_refs returns
pointers, not source. git_log shows what happened (commits + file list), not diffs.
See How it works to understand how basemind builds the map that makes this possible.
How savings are estimated
Section titled “How savings are estimated”The saved-token figure in basemind admin telemetry and the statusline is an estimate, not a measurement of
your session. For each call, basemind counts the response tokens and multiplies them by a fixed
per-tool factor modelling what a grep plus file reads would have cost:
| Tool | Factor |
|---|---|
code_symbols |
25x |
docs_search |
2.5x |
code_outline |
1.2x |
code_refs, find_files, code_grep, code_read, code_search, the git, memory and index tools |
1x (no saving claimed) |
The factors are calibrated from medians measured by basemind admin eval (see
Evaluation); a tool where basemind did not beat its baseline claims 1x.
Telemetry is keyed by tool name.
Treat the total as an order of magnitude.
Good habits the plugin sets up
Section titled “Good habits the plugin sets up”The plugin nudges agents toward the cheap path by default:
- Get a file’s outline before opening it — then read only the part you need.
- Search for a definition instead of grepping for it —
code_symbolsvsgrep. - Look up who calls a function instead of grepping for call sites —
code_refsvsgrep. - Refresh the index after edits —
index_rescaninstead of restarting the server. - Don’t re-read a file basemind already mapped — use the outline instead.
Guard: redirect wasteful searches
Section titled “Guard: redirect wasteful searches”The plugin ships a hook that enforces token discipline at the moment a tool is used. It is on by default:
BASEMIND_GUARD=nudge # default: allow the call, add a one-time advisoryBASEMIND_GUARD=redirect # deny the call and point at the basemind toolBASEMIND_GUARD=off # disableWhen an agent reaches for a built-in Grep or Glob search, the guard points it at the matching
basemind tool (code_grep for text, code_symbols for names, code_refs for call
sites). In the default nudge mode the call goes through with an advisory, shown once per session
per tool; redirect denies it. The guard needs jq and quietly does nothing without it.
Outline first, read on demand
Section titled “Outline first, read on demand”code_outline returns a file’s shape — signatures and imports, no bodies. code_read brings any
one symbol’s full body back when an agent actually needs it: read the outline, then read only the
symbol you need.