Token Saver is an open-source project for reducing avoidable LLM and AI-agent cost without hiding quality regressions behind a compression percentage.

Most token tools focus on one layer: command-output compression, usage dashboards, model routing, or code retrieval. Token Saver is being built as a quality-aware efficiency control layer that connects four steps:

Observe waste → Optimize safely → Verify task quality → Reconcile real cost

The current release is a lightweight OpenClaw skill. The next product milestone is Token Saver Doctor, a local-first CLI that identifies repeated context, cache-breaking prompt drift, oversized tool schemas, noisy logs, and other "ghost token" patterns.

Why Token Saver

Token waste is not a single compression problem.

The differentiator: cost per successful task

A smaller prompt is not automatically a cheaper task. If compression removes a required detail and the agent reruns a tool, rereads a file, or produces a wrong answer, the apparent saving disappears.

Token Saver's target metric is therefore:

Cost per successful task
= total provider cost, including retries and rework
  ÷ successfully completed tasks

The long-term product is designed around three connected layers:

1. Doctor — find where tokens are being wasted.
2. Gateway — apply safe, reversible optimizations with fail-open behavior.
3. Proof Ledger — compare original input, optimized input, provider usage, retries, latency, and task outcome.

Project status

[!IMPORTANT]
Token Saver is currently an early-stage OpenClaw skill, not yet a universal proxy or production cost-control platform.

Available now

• Task-complexity guidance for model selection
• Context hygiene for long conversations
• Concise-response rules
• Tool-call and file-read discipline
• OpenClaw-compatible SKILL.md

In development

• token-saver doctor for local transcript and configuration analysis
• A unified usage ledger backed by provider receipts
• Prompt-prefix and cache-hit diagnostics
• Repeated-context and repeated-file-read detection
• Reversible log and tool-output compaction
• Quality-aware replay and regression benchmarks
• Adapters for Claude Code, Codex, OpenCode, OpenClaw, Hermes, and other agents

See the full roadmap.

Quick start

Install as an OpenClaw skill

openclaw skills install token-saver

Or install manually:

mkdir -p ~/.openclaw/workspace/skills/token-saver
cp SKILL.md ~/.openclaw/workspace/skills/token-saver/SKILL.md

The skill acts as an advisory policy for every turn. It encourages the agent to choose an appropriate model, avoid repeated reads, compress resolved context, batch tool calls, and keep output proportional to the task.

Actual savings depend on the model, provider, agent, task mix, cache behavior, and whether the host supports model switching. Token Saver does not present estimated percentages as measured results.

What makes this different

Planned architecture

Claude Code / Codex / OpenCode / OpenClaw / Hermes / custom agents
                              │
                         Agent adapters
                              │
                 ┌────────────┴────────────┐
                 │      Token Saver        │
                 │                         │
                 │  Meter    Optimizer     │
                 │  Doctor   Quality Guard │
                 │  Cache    Replay        │
                 └────────────┬────────────┘
                              │
                    Local Proof Ledger
                              │
                         LLM provider

Design principles:

• Local-first — session analysis and optimization metadata stay on the user's machine by default.
• Fail-open — unknown formats or optimization errors forward the original request.
• Reversible where possible — compressed content keeps a path back to the original.
• Provider receipts win — provider-reported usage is the accounting source of truth.
• Quality before compression ratio — no optimization is successful if task quality falls.
• Adapter-based — agent-specific integrations remain separate from the core event model.

Read the architecture document.

Benchmark policy

Token Saver will publish claims only when they are reproducible. Every benchmark must report:

• fixed model and task set;
• baseline and optimized runs;
• original tokens, optimized tokens, and provider-reported usage;
• task success rate;
• retries and repeated tool calls;
• wall-clock time;
• cost per successful task.

Initial benchmark tracks are defined in docs/BENCHMARKS.md:

• codebase exploration;
• bug fixing with executable tests;
• long-running document conversations;
• CI and build-log diagnosis;
• support-ticket history analysis.

Roadmap snapshot

Target integrations

Repository structure

.
├── SKILL.md                  # Current OpenClaw skill
├── README.md                 # Canonical English documentation
├── README_CN.md              # Short Chinese overview
├── ROADMAP.md                # Product milestones
├── CONTRIBUTING.md           # Contribution guide
├── llms.txt                  # AI-readable project index
├── docs/
│   ├── ARCHITECTURE.md       # Planned system design
│   └── BENCHMARKS.md         # Reproducible evaluation policy
└── references/
    └── token-pricing.md      # Background cost notes

Contributing

The most useful contributions now are:

• anonymized token-waste patterns from real agent sessions;
• parsers for Claude Code, Codex, OpenCode, OpenClaw, or Hermes logs;
• reproducible benchmark tasks;
• safe, deterministic compaction recipes;
• provider usage and cache-accounting tests;
• documentation and installation feedback.

Read CONTRIBUTING.md before opening a pull request.

Search keywords

AI agent token optimization · LLM cost optimization · context engineering · context compression · prompt caching · token usage · AI FinOps · MCP optimization · Claude Code · OpenAI Codex · OpenClaw · Hermes Agent · Cursor · RAG optimization · local-first AI · reversible compression · agent observability

License

MIT — see LICENSE.