# A tool that installs hooks into your coding agent and then bills you less

> token-optimizer runs as a plugin and a set of hooks inside nine different coding agents, and the interesting part is the licence: PolyForm Noncommercial, which means the code is readable and reusable but you may not put it in a commercial product. Everything else about the design follows from that choice to be an open tool rather than a dependency.

**alexgreensh/token-optimizer** — Find the ghost tokens. Fix them. Survive compaction. Avoid context quality decay. 

- Repository: https://github.com/alexgreensh/token-optimizer
- Website: https://token-optimizer.dev
- Stars: 2,468 · Forks: 192
- Language: Python
- License: NOASSERTION
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/alexgreensh-token-optimizer

## The readme leads with badges, and the badge list is the feature list

There is a wall of badges before the first sentence of prose, and it is worth reading as documentation rather than decoration. There is a badge for cutting context waste, one for surviving compaction with checkpoint and restore, one for saving real money every session, one for a live dashboard showing tokens, dollars and turns, one for a live context quality score, and one saying tests are passing. Then a second row: zero dependencies, zero telemetry, Python 3.9 or newer, and a platform badge for three desktop operating systems. Then the licence badge, which is the most consequential line in the whole header. The claims that a tool makes about itself in a badge row are the claims it wants you to accept without reading, so the useful question is which of them are checkable. Zero dependencies and zero telemetry are checkable by reading the code, and the second one is the kind of thing that matters more than it looks for a tool that sits inside your editor and sees everything you type. A live dashboard of tokens, dollars and turns is a claim about instrumentation, and a context quality score is a claim about a metric the tool defines, which means the definition is the interesting part and is in the documentation rather than the badge. The subtitle underneath is more honest than the badges: it runs in the background, you keep working, and you run the audit when you want the full picture. That is the honest description of a hook-based tool, and it is the right mental model for deciding whether you want it. The repository has an install script at its root and a quickstart in the documentation, which is where the two-minute setup claim is documented:

```bash
https://alexgreensh.github.io/token-optimizer/start/quickstart/
```

## Nine agents, two of them beta, and one roadmap item

The compatibility sentence is a list and it is long. The tool works on one agent in both a command line and an editor form, plus eight others, of which two are marked as beta, and it names a ninth product as next on the roadmap. Supporting that many means one per product directory in the repository, and the top-level listing confirms it: separate directories for the command line plugin form, another plugin ecosystem, the editor extension, the assistant product, a hosted coding product, two more agent products, a beta product, plus a skills directory and a hooks directory. The badges in the header read their version numbers from each product's own manifest file rather than hardcoding them, which is a small detail that means the header cannot drift from the code. Two observations are worth making. First, the breadth is a maintenance liability, not just a feature: nine integration surfaces means nine things that break when a host changes how it invokes hooks or reads plugin manifests, and the release numbers suggest someone is dealing with that continuously. Second, the two beta labels are honest, because a hook that runs on every turn of a coding session is exactly the kind of integration that has edge cases, and saying so is better than implying uniformity. If you are evaluating this, count the agent you use rather than the list, and read the page for that agent rather than the general documentation.

## Hooks are the mechanism, and the repository documents them separately

The repository has a dedicated hooks directory and a separate document about hooks, which tells you the mechanism is not incidental. A hook is code the agent runs at defined points in a turn: before or after a tool call, when a session starts, when a context compaction happens. A tool like this needs them because the savings it claims are not things a user does once. The readme's summary is that you install it, run the audit once, and the hooks do the rest, which means the work happens continuously rather than on demand. The categories of waste it names are the substance: bloated configuration files, unused skills, stale memory, loss at compaction, model misrouting, and behavioural waste. Each of those is a different intervention. Configuration and skills are files you can edit once. Memory is state that goes stale and needs pruning. Compaction loss is a recovery problem, and the readme claims to address it with a checkpoint and restore mechanism, which is the most interesting of the claims because compaction is the point at which an agent discards its own earlier reasoning. Model misrouting is a cost problem where a cheaper model would have done. The category that is hardest to define is behavioural waste, and a tool that claims to detect it is making a judgement about your working style, which is where you should be most sceptical and where the documentation matters most.

## The competitive claim is a percentage, and percentages like that are worth unpacking

The readme has a section titled why not use the alternatives, and it names two competing tools and makes a specific arithmetic claim: those tools compress command output, which covers fifteen to twenty-five percent of your context, whereas this tool covers that plus the other seventy-five percent. The number is doing a lot of work and none of it is sourced. A claim of that shape, a competitor's coverage stated as a range and the remainder assigned to the author, is a rhetorical construction rather than a measurement, and the readme does not describe how either figure was obtained. What is checkable is the shape of the argument, and it is a reasonable one. Compressing command output is a local, bounded intervention: it helps when a tool returns a large result and does nothing about a bloated instruction file or a context that was thinned by compaction. The broader claim is that most of a coding agent's context is not tool output, and that is plausible, because a session accumulates instructions, file contents, prior turns and tool results, and only one of those is compressible after the fact. Whether the other categories are as compressible is the question the audit is supposed to answer, and running the audit on your own workload is the only way to find out. A competitor comparison you cannot reproduce is a marketing line, so treat it as one and read the audit output instead.

## PolyForm Noncommercial, and what it rules out

The licence badge says PolyForm Noncommercial, and the repository's licence field is recorded as a custom licence GitHub cannot classify, with a licence file at the root. PolyForm Noncommercial is a source-available licence: you can read the code, modify it, run it, and self-host it, and you cannot use it as part of a product you sell or as a component of a service you charge for. The practical effect is that a company can adopt this internally, which is presumably the intended audience, and cannot vendor it into a commercial product, cannot wrap it in a paid offering, and cannot rely on it as a dependency in something you distribute. That is a real constraint and it is worth reading before installing rather than after, because the failure mode is discovering it during a licence review. The licence choice also explains several other things about the project. It is why the tool is a plugin and a set of hooks rather than a library you import, since a hook runs inside someone else's product rather than becoming part of yours. It is why there is a sponsor link in the header asking for support to keep it open, which is how a source-available project funds itself. And it is why the privacy document and the zero-telemetry claim are stated as prominently as the features, because a tool that inspects your context is asking for trust, and the author knows the licence already limits who can adopt it commercially.

## Benchmark files, checksums, and what the repository says about itself

A few top-level entries say more about the project's posture than any badge. There is a benchmark document and a separate controlled one for a specific comparison, which suggests the author is trying to make the savings claims falsifiable rather than rhetorical, and those two files are where you should look first if you want to argue with the tool. There is a checksums file, which is unusual outside of release engineering and implies the distribution is verified somewhere. There is a signatures directory, which implies signed artefacts. There is a security document and a privacy document, both of which for a tool that reads your prompts and rewrites your context are not optional reading. There is a changelog, a commands directory, a scripts directory, a skills directory, a tests directory, a design directory, a documentation site with its own source, and a development-work directory. Read together, that is a project with release engineering, a test suite, an audit trail and a documentation site, which is a lot of process for a tool whose premise is that it runs invisibly. The release cadence is the last thing to weigh. The recent versions are three days apart, and the newest is at patch level sixteen on a minor version thirteen, which is a project shipping very often. That is good for keeping up with host changes and bad for pinning, since you can expect the behaviour of a version you tested to be replaced within days unless you hold it.

## Conclusion

Adopt token-optimizer if you pay per token for a coding agent and suspect you are paying for output nobody reads, since the readme's own claim is that installing it and running one audit is the whole setup and the rest runs on hooks. Do not adopt it inside a commercial product, because the licence is PolyForm Noncommercial, and check that restriction before anything else since it is the one thing here that cannot be worked around. Four things to verify. Which agent you actually use, since support spans nine of them with two marked as beta and the hook mechanism is not identical across all of them. Whether the savings are on your workload, because the readme's own comparison claims a share of the saving comes from command output compression, which the readme attributes to competing tools covering fifteen to twenty-five percent of context, and the rest comes from configuration, skills, memory and routing. Whether you are willing to have a tool inspect and rewrite your context between turns, since that is what hooks do and the readme's claims about surviving compaction rest on it. And whether the release cadence suits you, because the version numbers show releases several times a week, which means change arrives whether or not you want it. The last push was on 2026-09-17.

## FAQ

### What does token-optimizer actually do?

It installs hooks into your coding agent that cut wasted context, keep work across sessions and compactions, and feed a dashboard of tokens, dollars and turns. The readme says most of it runs automatically after you install it and run the audit once, and it names the categories it targets as bloated configs, unused skills, stale memory, compaction loss, model misrouting and behavioural waste.

### Which coding agents does token-optimizer support?

The readme lists one agent in both command line and editor form, plus eight others, of which two are marked as beta, and names a further product as next on the roadmap. The repository has a separate directory per agent integration, and each version badge reads from that agent's own manifest.

### Can I use token-optimizer in a commercial product?

No. The licence is PolyForm Noncommercial, which permits reading, modifying, running and self-hosting but not using the project as part of a product you sell or a service you charge for. Internal use in a company is the intended audience.

### How does token-optimizer compare to the other context tools?

The readme says the alternatives compress command output, covering fifteen to twenty-five percent of context, and claims this tool covers that plus the rest. The repository includes a benchmark document and a second controlled comparison document, which are the place to check those figures rather than the readme's summary.

### What are token-optimizer's system requirements?

Python 3.9 or newer, a badge says zero dependencies and zero telemetry, and the supported platforms are macOS, Linux and Windows. The repository includes a tests directory and a changelog.

### How often is token-optimizer released?

Very often. The three most recent releases are three days apart, at patch level sixteen of a minor version thirteen, and the last push to the main branch was on 2026-09-17. A version you test is likely to be superseded within days unless you pin it.

## Sources

- [alexgreensh/token-optimizer on GitHub](https://github.com/alexgreensh/token-optimizer)
- [Issues](https://github.com/alexgreensh/token-optimizer/issues)
- [Project website](https://token-optimizer.dev)
- [README](https://github.com/alexgreensh/token-optimizer/blob/main/README.md)
- [Releases](https://github.com/alexgreensh/token-optimizer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alexgreensh-token-optimizer