Token Saver

A small, vendor-neutral efficiency pack for AI coding agents working on large codebases.

Use less context. Keep the engineering signal.
Complements, never collides.

The npm badge above is the authoritative published version. See CHANGELOG.md for release history and unreleased changes.

5-second view

                         TOKEN SAVER
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ↓                     ↓                     ↓
   Historical            Current code          CLI output
   knowledge              structure             / logs
        │                     │                     │
        ↓                     ↓                     ↓
  Semantic memory       Code intelligence       RTK-style
   (Supermemory)          (jCodeMunch)          optimization

Large general context  ───────────────→  Context assurance (Entroly)
Exact/canonical evidence ─────────────→  RAW / untouched

The rule is simple: use one appropriate optimization/intelligence layer for each context surface, and leave exact engineering evidence exact.

Install

All supported managed-install methods target ~/token-saver.

Recommended: npm / npx

No global install is required:

npx @sudowhat/token-saver@latest install

Bun

bunx @sudowhat/token-saver@latest install

pnpm

pnpm dlx @sudowhat/token-saver@latest install

Permanent CLI (optional)

If you prefer a globally available token-saver command:

npm install -g @sudowhat/token-saver@latest
token-saver install

curl (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/sudowhat/token-saver/main/install.sh | sh

The curl installer downloads the latest GitHub Release and verifies its SHA-256 checksum before installing.

PowerShell

irm https://raw.githubusercontent.com/sudowhat/token-saver/main/install.ps1 | iex

Git / another version-control checkout

git clone https://github.com/sudowhat/token-saver ~/token-saver

If ~/token-saver is a Git checkout, Token Saver installers deliberately refuse to overwrite it; update it through its version-control workflow instead.

Start an agent

From any AI-assisted software project, give a new agent this as its first instruction:

Read ~/token-saver/AGENT.md and initialize this project. Then continue to follow it for this session.

After that, interact with the agent normally. You should not need to repeatedly tell it which optimization tool to use.

Update normally

For npm/npx installations:

npx @sudowhat/token-saver@latest update

For Bun:

bunx @sudowhat/token-saver@latest update

For a globally installed CLI:

npm install -g @sudowhat/token-saver@latest
token-saver update

For curl/PowerShell installs, rerun the same installer command. Managed installers refuse to overwrite locally changed Token Saver files unless an explicit force path is used.

Useful CLI commands:

token-saver install
token-saver update
token-saver doctor
token-saver version
token-saver print-init
token-saver uninstall

The short token-saver ... form is available when the npm package is installed globally. With npx/bunx, prefix the command with the corresponding runner.

What Token Saver does

Token Saver combines five complementary ideas/tools, while keeping your actual project files, source code, tests, project instructions, and current version-control/workspace state authoritative:

| Layer | First reference | Best for | |---|---|---| | Token discipline | Caveman + selected Beeline principles | Avoiding unnecessary reads, tool calls and agent chatter | | Semantic memory | Supermemory | Finding relevant historical decisions, regressions and lessons | | Code intelligence | jCodeMunch | Symbol/AST navigation, relationships, blast radius and bounded current-code retrieval | | CLI output optimization | RTK | Compressing noisy build/test/log output | | Context assurance | Entroly | Reducing large general model-bound context with recovery/provenance |

The external tools are optional and are not bundled in this repository.

Complements, never collides

Token Saver is a compatibility/optimization layer, not a replacement agent framework.

Project rules win. If one Token Saver capability conflicts with an authoritative host-project rule, the agent suppresses only that capability and falls back to the project's native workflow for that surface. Unrelated Token Saver capabilities may continue normally.

Conflicts are reduced by design because:

• project instructions are read before Token Saver optimization is applied;
• each context surface has one optimization/intelligence owner;
• external providers are optional;
• exact/canonical engineering evidence has a RAW path;
• every optional provider has a native fallback;
• provider-supplied planners, prompts, hooks and enforcement remain subordinate to Token Saver and project policy;
• Token Saver does not require a specific AI vendor, IDE, MCP host, external tool, or version-control system.

Token Saver cannot technically guarantee that every AI host will implement instruction precedence perfectly, so the policy is deliberately conservative: when uncertain, yield to the project/native path.

Provider boundary: jCodeMunch

jCodeMunch is Token Saver's first reference provider for the current-code surface. Its core model fits Token Saver well: index the code structurally, locate the relevant symbol/relationship, retrieve only the necessary source, and keep the live project authoritative.

Use its structural capabilities for things such as symbol retrieval, outlines, importers, call/class hierarchy, blast radius, changed symbols, AST/structural searches, hotspots and bounded code-context bundles when the installed version supports them.

jCodeMunch has also grown into broader agent tooling: task-context assembly, turn planning, compact response encoding, risk checks, configuration auditing, prompt policies, watchers and optional enforcement hooks. Token Saver deliberately does not give those features global ownership.

jCodeMunch structural code intelligence
                 ↓
        targeted code context
                 ↓
              model

not

jCodeMunch targeted context
                 ↓
      another compressor/planner
                 ↓
              model

A jCodeMunch planner/context assembler may optimize operations inside the code-intelligence surface. Cross-surface routing remains Token Saver's job. Provider prompt policies/hooks never outrank the target project's rules, and must not block a required RAW/native exact-source read.

Evidence without marketing inflation

jCodeMunch currently publishes a reproducible benchmark reporting 96.4% fewer code-retrieval tokens than its grep-top-3 baseline across 15 task runs (per-query results vary widely; see upstream methodology), plus a separate production-codebase A/B report with smaller tool-layer savings. Token Saver treats those as provider-specific retrieval evidence—not as a promise that every complete coding session will be 96.4% cheaper.

See the current upstream README/benchmark methodology for exact versions, caveats and reproducibility details: https://github.com/jgravelle/jcodemunch-mcp

Routing rule

exact / canonical / gate evidence        -> RAW / native exact path
historical engineering knowledge         -> semantic-memory provider
current source-code structural retrieval -> code-intelligence provider
CLI / shell stdout or stderr             -> CLI-output optimizer
large reconstructible general context    -> context-assurance provider
anything else                            -> native/direct path

This prevents collisions such as RTK output being compressed again by Entroly, or jCodeMunch's already-targeted source being passed through another compressor.

Important safety rule

Optimization never overrides correctness.

Source being edited, exact diffs/changesets, security-sensitive evidence, test failures, machine-readable gates and current version-control/workspace state must remain exact whenever the decision depends on their exact contents.

If any optional provider is missing, stale, unsupported, unsuitable or conflicting, the agent falls back to normal targeted search/read/build/test commands.

For code indexes specifically, remember that index/cache state is another source-derived copy. Protect it like source code, verify freshness/coverage before absence or blast-radius conclusions, and keep the project's own secret scanning/access controls authoritative.

Releases and versioning

Token Saver follows Semantic Versioning:

PATCH  fixes / safety / installer corrections
MINOR  backward-compatible skills, providers or capabilities
MAJOR  incompatible bootstrap, CLI, routing or precedence changes

Every release keeps these aligned:

package.json version
Git tag vX.Y.Z
npm @sudowhat/[email protected]
GitHub Release vX.Y.Z
CHANGELOG.md

See CHANGELOG.md for human-readable release notes.

Repository layout

token-saver/
├── AGENT.md
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── package.json
├── bin/token-saver.mjs
├── install.sh
├── install.ps1
├── INIT_PROMPT.txt
├── OPTIONAL_PROJECT_STUB.md
├── THIRD_PARTY.md
├── LICENSE
└── skills/
    ├── token-discipline/SKILL.md
    ├── semantic-memory/SKILL.md
    ├── code-intelligence/SKILL.md
    ├── cli-output-optimization/SKILL.md
    └── context-assurance/SKILL.md

There is intentionally no nested agent-efficiency-pack directory. token-saver is the pack.

Large C/C++ projects

The code-intelligence layer is especially useful on large C/C++ codebases: structural indexing can locate symbols, implementations, callers, inheritance relationships and blast radius before the agent reads source. If SCIP/clang-derived reference data already exists, it may optionally improve accuracy.

The index is still not live truth: stale or incomplete results must fall back to current native source/search.

Contributions welcome

Token Saver is intended to improve through real developer usage.

Contributions are welcome for better routing rules, additional toolchains/languages, measurable token/context savings, safer fallback behavior, and new reference providers. A proposed new tool should ideally fill a distinct surface rather than duplicate an existing layer.

New token-saving tools enter the pack only when they complement rather than collide with existing Token Saver layers and the host project's own rules.

See CONTRIBUTING.md for the design principles and what makes a useful addition.

Licensing

This Token Saver repository is MIT licensed.

Referenced external tools retain their own licenses and commercial terms. In particular, jCodeMunch is currently source-available under a dual-use license rather than a conventional permissive open-source license. Its current upstream terms require a paid license for commercial/for-profit use. Token Saver references it as an optional provider and does not bundle or redistribute it.

Always verify the current upstream terms for any provider before enabling it in your environment. See THIRD_PARTY.md for links and notes.