Skip to content

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.

When you ask “where is the User class defined?”, basemind returns:

src/models/user.ts:42

Reading 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.

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.

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_symbols vs grep.
  • Look up who calls a function instead of grepping for call sites — code_refs vs grep.
  • Refresh the index after edits — index_rescan instead of restarting the server.
  • Don’t re-read a file basemind already mapped — use the outline instead.

The plugin ships a hook that enforces token discipline at the moment a tool is used. It is on by default:

Terminal window
BASEMIND_GUARD=nudge # default: allow the call, add a one-time advisory
BASEMIND_GUARD=redirect # deny the call and point at the basemind tool
BASEMIND_GUARD=off # disable

When 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.

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.