Token saviour

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.

1. "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%).

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

3. 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).

4. 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.)

5. 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>     # e.g. rtk test pytest      → only failures + summary
rtk read  <files...>     # cat with filtering
rtk grep  <pattern> <p>  # compact grep (groups, truncates); -t py to scope by type
rtk find  <find args>    # compact file listing
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.