| name | token-saviour |
| description | Pick the most token-efficient tool for a coding task instead of reflexively reading whole files, dumping raw command output into context, or writing more code than asked. Use this skill BEFORE you explore or explain a codebase, locate a symbol/definition/callers, trace a call path, map an architecture, plan or implement a feature across layers, or run verbose commands (tests, builds, git, grep, directory listings) — and whenever context/token budget, cost, or "make this use fewer tokens" comes up. It routes the scenario to serena, rtk, caveman, Ponytail, or plain tools, with concrete commands and the combinations to use vs. avoid. Reach for it even when the user doesn't name a tool: if you're about to `cat`/Read several files, or about to generate a big implementation, that's the trigger.
|
token-saviour: spend tokens where they matter
Reading whole files to answer a narrow question is the single most wasteful thing an agent
does. On a benchmark over a ~30-file Python app, swapping whole-file reads for semantic
retrieval cut total tokens ~66%; the other tools each own a narrower slice. This skill
helps you reach for the right one before you blow the context budget — then get back to the
actual task.
The mental model: token cost has four independent layers, and a different tool owns each.
Match the tool to the layer the task actually stresses. These winners were re-validated in a
9-tool benchmark (2026-07) against newer entrants (archex, Pare, lazy-cat) — every incumbent
held its layer; the runner-ups and the niches where they flip are in
references/tool_links.md.
| Layer | What it is | Tool | Don't bother with |
|---|
| Code-read input | Understanding code: symbols, callers, call paths, architecture | serena | rtk, caveman, Ponytail |
| Command-output input | Verbose stdout: tests, builds, git, grep, listings | rtk | the code-read tool |
| Generated prose output | Your own long, chatty replies / write-ups | caveman | the input tools, Ponytail |
| Generated code output | Implementations you write/edit | Ponytail | the input tools, caveman |
| — | Tiny/one-off work | plain Read/Grep/Bash | everything (overhead > benefit) |
First, check availability. These are optional third-party tools. Run the relevant
--help/--version once; if a tool isn't installed, see references/tool_links.md for
install + verify commands, or fall back to the next-best option in its row (ultimately plain
Read/Grep/Bash). Never pretend a tool ran — degrade gracefully.
Announce what you used. Whenever this skill drives a task, print a one-line tag naming the
token-saving tools actually used, joined with + — e.g. 🪙 token-saviour: serena + rtk + caveman, or 🪙 token-saviour: serena + ponytail. If you fell back to plain Read/Grep/Bash
because nothing was installed or the task was trivial, say so: 🪙 token-saviour: plain tools (fallback). List only tools you genuinely invoked, in layer order (serena → rtk → caveman
/ ponytail).
Decision guide
Work top-down. The moment a row matches, use that tool and stop.
-
"Where is X / what calls X / how does A reach B / what breaks if I change X / explain this
module / list its methods?" → serena (semantic code retrieval). This is the dominant
cost — code-reading was ~88% of the baseline bill — so this is the highest-value switch.
Measured: tracing a 4-layer call path cost 65 tokens vs 1,633 reading the files (−89%);
explaining the whole architecture 243 vs 3,250 (−85%); listing one class's methods 55
vs 458 (−71%); finding all callers 49 vs 525 (−78%).
-
Running something noisy — test suite, build, linter, git, grep, a big directory
listing → rtk (compresses command output). Measured: the test run −65%, the
structure listing −38%. Its win scales with verbosity, so it's biggest on failing test
dumps and long build logs (this clean repo is a lower bound). Niche exception: if your
loop is dominated by test runs and Pare's MCP servers are already wired in, Pare's
structured pytest posted the single best command result we measured (−72%: pytest: 13 passed, 5 tokens) — but it adds tokens on listings/greps, so rtk keeps the layer.
-
About to write a long, prose-heavy answer (explanations, write-ups, status) → consider
caveman (terse "caveman" reply style). It trims filler/hedging/pleasantries. Small on already-concise text and it
can grow terse list/structured output by adding markdown — so use it for genuinely chatty
output, not for short factual answers or anything where exact wording/order matters
(warnings, irreversible steps, ordered procedures).
-
About to generate or edit a chunk of code (implement a feature, scaffold, refactor) →
Ponytail (a "lazy senior dev" rules plugin that biases you toward minimal code). It
applies YAGNI: skip unrequested abstractions/helpers, prefer stdlib + one-liners, delete over
add. In our benchmark it trimmed a verbose due-date implementation by ~40% (illustrative —
the size depends on how much scope the baseline over-built) by dropping helpers and a derived
property nobody asked for. It does ~nothing on prose — it's the mirror image of caveman.
(lazy-cat performed equivalently under the identical framing; Ponytail keeps the slot for its
intensity levels and explicit don't-simplify guardrails.)
-
None of the above / a one-file, one-line lookup → just use plain Read/Grep/Bash. The
tools have setup and call overhead; on tiny tasks that overhead can cost more than it
saves. Don't tool-ify trivial work.
serena owns the code-read layer
serena cuts the dominant cost — code-read input — by returning just the relevant
structure instead of whole files. It's comprehension- and edit-heavy: broad multi-file
understanding plus semantic edits/renames. Best measured on listing a class's members
(−71%) and whole-architecture explanation (−85%), with strong caller and call-path lookups too.
It needs a language server and indexes once at session start.
If you reach for only one tool, make it serena — it's the only lever that moves the dominant
(code-reading) cost. (Runner-ups if serena is unavailable: graphify for call-path navigation,
CodeGraph as a zero-config single binary — see references/tool_links.md. Skip retrieval-bundle
tools like archex on small/medium repos: their fixed per-query overhead measured worse than
just reading the files, +15% on our suite.)
Best combinations, and what to avoid
The four layers are independent, so combining one-per-layer is additive:
- 🥇 Comprehension / navigation work: serena + rtk + caveman. Each owns a
distinct slice; rtk and caveman cost ~nothing to add. Measured combined: −70% (the best
stack in the 9-tool re-run; the Pare variant landed at −67%).
- 🥇 Code-generation work: serena + Ponytail — swap caveman→Ponytail because the
output is code, not prose. On the codegen task ≈ −64% (the code-read half measured, the
Ponytail half illustrative).
- ❌ Don't reach for rtk to fix comprehension cost — it's ~0% there. Use it for
command-heavy loops.
- ❌ Don't run two code-read tools (serena / graphify / CodeGraph / archex) together — two
integrations, one benefit. Pick one.
- ❌ Don't mix up the two output tools — caveman shrinks prose (~0% or worse on code);
Ponytail shrinks code (~0% on prose). Route by whether the output is prose or code.
- ❌ Don't expect any output tool to move an input-heavy bill — when you're reading lots of
code, output is a small share; serena is what matters.
Install missing tools
When a chosen tool is absent, read references/tool_links.md and install the smallest useful
set:
- serena for symbol-aware comprehension/edits — the one code-read tool.
- Add
rtk only for noisy command loops.
- Add
caveman only when prose-output brevity is the bottleneck.
- Add
ponytail only when code-generation work is the bottleneck.
For network installers or shell profile changes, request approval if the environment requires it.
Tool quick-reference (commands)
Use these in place of the reflexive Read/Grep/Bash/"write it all out" equivalents.
Install/verify details for any missing tool: references/tool_links.md.
serena (MCP server, LSP) — instead of reading files to understand/edit code
Connect to the serena MCP server for the project, then call tools rather than reading files:
get_symbols_overview(relative_path) — top-level symbols in a file (add depth: 1 for methods).find_symbol(name_path_pattern, relative_path, include_body=true) — a symbol's body.find_referencing_symbols(name_path, relative_path) — every caller, with context.- Edits too:
replace_symbol_body, insert_after_symbol, rename_symbol.
rtk (Rust CLI proxy) — instead of raw verbose commands
rtk test <test cmd>
rtk read <files...>
rtk grep <pattern> <p>
rtk find <find args>
rtk ls / rtk tree / rtk git / rtk diff / rtk log ...
caveman — instead of a long, chatty prose reply
Activate terse mode (say "caveman mode" / /caveman, levels lite|full|ultra) when you're
about to emit a verbose explanation. Keep code blocks, commands, API names, error strings, and
ordered/irreversible steps verbatim — caveman compresses prose, not substance.
Ponytail — instead of writing more code than the task needs
Enable the plugin (/ponytail lite|full|ultra) before generating an implementation — prefer those
modes so the code stays complete and readable. Its rules: don't build what wasn't requested (YAGNI),
prefer stdlib/native + one-liners, no speculative abstractions/helpers, delete over add, leave one
runnable check. It stays out of your way on input validation at real trust boundaries, error handling,
and security.
Why this works (so you can adapt it)
Input dominates the bill when an agent works in a codebase (it was ~88% in the benchmark), and
most of that input is over-reading — pulling entire files to answer something a symbol lookup
answers in a fraction of the tokens. Semantic retrieval wins because it returns just the
relevant structure. rtk, caveman, and Ponytail look small in aggregate only because they target
narrow slices — but they're cheap, so stack them. The one trap is treating these as
interchangeable: each is excellent in its lane and ~useless outside it. When in doubt, ask
"which layer is this task spending tokens on — reading code, reading command output, writing
prose, or writing code?" and pick that row.
Full evidence (per-task tables, the 9-tool comparison, limitations):
references/benchmark_results.md.
