vukkt/token-warden

token-warden

A Claude Code plugin that makes coding agents measurably cheaper over time.

Most "agent memory" accumulates advice nobody ever verifies. token-warden treats agent memory as an engineering problem: every rule that wants space in an agent's context must prove, on a fixed benchmark, that it saves more tokens than it costs — or it gets evicted. The result is a per-agent memory file containing only rules with measured, positive return.

• Measured, not vibes — every rule carries a token delta from real benchmark runs
• Self-funding — rules must save ≥ 2× their own context rent to stay
• Self-auditing — active rules are re-benchmarked round-robin and evicted when they stop earning
• Zero session overhead — collection runs in a Stop hook that never blocks or fails your work

---

Table of contents

• How it works
• Getting started
• Commands
• The benchmark system
• Architecture
• The agents
• Inter-agent approval gate
• Design invariants
• A recorded demonstration
• Testing
• Data layout
• Security notes
• Roadmap
• Contributing

---

How it works

The optimizer is a four-stage, feed-forward loop. Lessons are extracted from finished sessions and applied to future ones — past work is never re-done.

                  agent session (any project, any repo)
                                  │