Cut wasted context.

Thinker helps your coding agent use fewer tokens. Find what it loads but rarely uses, review what to cut, and reuse what it learns about your code.

npx @zerotimedev/thinker

Connect your agents, see suggested savings from recent sessions, and keep coding. Installation details.

  1  import decimal
  2  from dataclasses import dataclass
  3  from .money import Money, round_half_even
  …
140  def apply_refund_cap(invoice, refund):
141      cap = invoice.total * REFUND_CAP
142      if refund.amount > cap:
143          raise RefundTooLarge(refund, cap)
  …
612      return Invoice(lines=lines, total=total)

lines 128–181 of 612, round "refund_cap":
128  REFUND_CAP = decimal.Decimal("0.5")
  …
140  def apply_refund_cap(invoice, refund):
141      cap = invoice.total * REFUND_CAP
142      if refund.amount > cap:
143          raise RefundTooLarge(refund, cap)
  …
omitted 1–127: imports, Money, Invoice, InvoiceLine
omitted 182–455: build_invoice, add_line, total
omitted 456–612: to_pdf, send
read any range: Read with offset and limit

Keep the knowledge, too. Thinker learns from your sessions and brings relevant notes into future tasks, checking them as the code changes. How the cache works.

Install and start saving

npx @zerotimedev/thinker

Requires Node 20+, git, curl, tar and a supported coding agent. The installer connects your agents and shows where their context goes. Choose the browser or terminal to review suggested cuts.

1. Find Savings: review the suggested instructions, skills and tools to shorten or switch off.
2. Apply your choices: preview instruction changes as a diff; in the browser, open a pull request to review and merge.
3. View Report: track tokens and costs week by week as you keep working.

After that, thinker comes to you. You don't run it by hand. About once a week, once a repository has ten sessions to read, your agent opens its reply with a short message from thinker: one line per change worth making, what it would have saved and the suggested action, with a link to the page. Reply with the numbers to approve, or "all", or review them on the page first; nothing changes until you say so. Whenever you want the page itself, thinker ui opens it. Learning, re-checking notes and updates run in the background.

Find Savings

Find Savings opens from the link in the weekly suggestion, or with thinker ui. See what each instruction, skill and tool costs your sessions, then choose what to cut.

Why a few thousand tokens matter

An agent's context is sent whole on every model call. The instruction file, the skill list, every MCP server's tool definitions and every tool result so far are re-read each time, and a coding session makes tens of calls. So a part's cost is its size times the calls: a 4k-token section read by 40 calls is 160k input tokens, and a 7k-token file read on the third call is paid on every call after it.

Two things follow. A token cut from the fixed part is cut from every call, so a 1,200-token section nobody acts on costs far more than its size suggests. And a tool result is cheap once and expensive as it stays: compressing it saves on every call that follows, not only the one that read it.

What it shows

Input tokens over time, as stacked columns by day or week, total or per session, split into the parts the agent reads on every model call. The page sorts by the cost a session: tokens times model calls.

One part at a time, as cards. Each instruction section, skill and tool stands beside three measures:

All repositories merges every repository's report: the timeline side by side, tools merged by name, averages weighted by sessions.

What you can cut

Choose a cut, review its preview, then apply it. Each action is also available from the terminal.

Compress or remove an instruction section

Pick the sections no session acts on. Compress has a model rewrite them to about a third of the length; it is told to keep every rule, command, flag, config key, default and path, and to drop history, measurements, rationale and repetition. Remove drops the section; a heading with subsections keeps its heading line.

How

Apply starts the change in the background and the page says so once: a model compresses the sections, and the change becomes one commit on a branch of its own, built from the default branch and pushed to the origin, with a pull request opened through gh; nothing in your working tree changes, and you read the diff in the pull request. Recent activity (the tab at the right) follows it: Compressing… while it runs, PR pending until it is merged, Merged (while your checkout has not pulled the merge, the section is not offered on Find Savings and Recent activity says which branch to pull), Rejected if it is closed without merging (the sections are suggested again), Failed with the reason and a Retry; the badge on the tab counts what still needs you. Without a GitHub origin or gh, the text is written to AGENTS.md (or CLAUDE.md) in your working tree instead, uncommitted, for you to review with git diff.

Undo

Close an unmerged pull request from Recent activity or GitHub. Revert a merged change through git; restore an uncommitted edit from the working tree.

Agents

Every agent that reads the file.

Switch skills, MCP servers, plugins and built-in tools off

A skill's description, an MCP server's tool definitions and a plugin's are loaded into every session whether or not anything uses them. Switch off takes one out of the next session's context for this repository. A skill switched off still runs when you type /name. Claude Code's own tool definitions go the same way, from the Built-in tools table (their rows in bold), after a confirmation that names the tools, where the switch is written and how they come back; the file, shell and search tools are never offered.

How

The setting in the agent's own files that hides the source, written for this repository alone. Claude Code: skillOverrides (user-invocable-only), enabledPlugins, disabledMcpjsonServers and, for a built-in tool, permissions.deny in .claude/settings.local.json; or disabledMcpServers in this repository's entry of ~/.claude.json, what /mcp disable writes. Codex: enabled = false in the checkout's .codex/config.toml, a skill by its path in ~/.codex/config.toml. Cursor: the server's entry in ~/.cursor/mcp.json, for every repository. Every file is backed up first under ~/.thinker/state/harness-backups/.

Undo

Turn back on: each file is put back as it was.

Agents

Claude Code and Codex; Cursor for MCP servers.

Compress tool outputs

A tool result stays in the conversation, so every model call after it reads it again: a whole-file read is paid for twenty times over. Compression keeps what the agent was looking for and names what it left out, so the agent can ask for any range.

How

Claude Code's tool hook may replace a result before the model reads it; nothing thinker serves ever leaves the context again, so this is the one place tokens are taken out instead of added. Three shapes are trimmed. A whole-file read becomes the lines around the session's recent search patterns and the request's identifiers, every omitted range named with the definitions it holds and a last line saying how to read it. A test run becomes its counts and each distinct failure once, the full log kept under .thinker/state/tests/. A large search becomes its hits grouped per file. Any other output past the cap is cut to it: 40 lines each side of a hit, about 3k tokens of plain output. A file under 120 lines, one with no hit, or one where the kept lines reach 60% of it passes whole.

Measure

After you change compression, the tool is measured from that setting onward. Its previous measurement stays as a muted row for comparison, below current rows.

Undo

No compression on the page. It is a setting in .thinker/config.json; nothing already in a conversation changes.

Agents

Claude Code only.

Correctness and undo

Every cut removes something the agent might have read. What keeps that from costing you a task:

• Nothing is cut by itself. The report measures. Each cut is your choice, shown first as a diff, a setting or a sample result, and each has an undo path.
• Use is measured before you cut. A section applied in 90% of sessions wastes a tenth of its cost at most, and is flagged only when that tenth is still a large share of the file. Start with high waste: large, and used in almost no session. The saving shown is the most a cut can save; a session that needed the part goes without it.
• Compression keeps the rules. The model that shortens a section is told to keep every instruction, command, flag, default and path and to drop history, numbers and rationale, and you read the diff in the pull request before merging it. Remove is yours to judge; in doubt, compress.
• A trimmed result says what it left out. A compressed file read names each omitted range and how to read it back, so the cost of a wrong guess is a second read, not a missed fact. A file the trim would not shorten passes whole, and full test logs stay on disk.
• You can undo a cut. Close an unmerged instruction PR or revert a merged change; use Turn back on for anything switched off, No compression for compression; Revert under Recent activity covers both. The FAQ lists what each cut writes.

What the numbers are. Tokens are counted from the transcripts at about four characters a token, times the model calls the transcript records. A tool output's cost is its tokens times the calls left after it; a compaction, which drops old results, is not seen, so that part is an upper estimate. The waste flags are measurements of use, not a promise: whether the agent then misses a cut section is what followed and missed are there to show, on your own sessions. No benchmark is claimed for the cuts; the benchmarks are about the cache.

Supported agents

Thinker works inside the tools you already use. Four agents are wired once per machine in their own settings; four more get an extension or hook file in the checkout.

The installer wires the agents it finds; its --clients option (all or a comma-separated list) picks them by hand. Restart a running agent after the install.

What a note is

A note answers a recurring question about the repository, not "what this file does". It is 3 to 12 lines with file:Symbol pointers into the code, and it comes in four kinds:

Each note stores its title, the questions it answers, its body, the files and symbols it rests on with their content hashes, its source (a session, a pull request, a person), its confidence and its status. A note's pointers are its dependencies: a note about AuthManager.verifyToken hashes that definition alone, so it does not go stale because another method in the same file changed.

Keeping it current

A cache that drifts from the code is worse than none. Thinker keeps itself correct in three ways, all in the background, under a daily token cap (maintain.dailyTokens in the configuration):

It learns from every session

• Each session is distilled once, when it ends, through the agent's own login: up to three new notes, and a verdict on every note it was served. confirmed (the agent acted on it) raises confidence; contradicted (the trace shows a claim was wrong) corrects the body and keeps the history; unused lets it decay. Near-duplicates are merged. A quiet session with nothing to learn from is skipped.
• Newly merged pull requests are mined as they land, fixes first, when maintain.prs is on in the configuration (off by default: the cache grows from the sessions).
• People add notes too: telling your agent to remember something makes it a note when the session is distilled.

It knows when a note is stale

• Every serving re-hashes the dependencies of every note against your working tree, uncommitted edits included. A note whose code changed is marked stale and names exactly what changed.
• A stale note is never served by the hooks. It is held back, re-verified in the background, and served again once it is fresh.
• Verification sends the note, the diff of its changed dependencies and their current text to a small model, which answers still_valid, update (body rewritten, history kept) or invalid (retired).
• The block is found by a tree-sitter parser for Python, JavaScript, TypeScript, Go and Rust, which comes with the install. Other languages, and code the parser cannot read, use a regex heuristic.

It maintains itself

Maintenance runs from the prompt hooks and after every commit or merge, and spends little by default: one verification batch every three days, of the stale notes served in the last three days (at most 50), retrieval phrasings for new notes, and the removal of notes nobody was served in 14 days (a committed note is archived instead). Mining pull requests, reading design documents and carding skill files in the background are off unless the repository's maintain configuration turns each on. What a run did is shown once at the end of the next turn.

Skills

A skill is a file (SKILL.md) an agent pulls into its context by name: how to deploy, how to run the tests here, how to add a webhook. Its instructions rest on code that moves, so a skill decays the way a note does. Thinker treats the skill files checked into a repository as cached knowledge; it never edits one.

• Each skill gets a card. A skill file under .claude/skills, .agents/skills, .codex/skills, .cursor/skills, .github/skills or skills/ gets a note of kind skill: what it is for, when to invoke it, what it prescribes, with pointers at the code it talks about. Maintenance cards new and changed files where maintain.skills is on. A served card tells the agent to invoke the skill for the full instructions.
• A card is served like any note. The hooks rank it with the rest, so a request the skill is about brings the card with its pointer to the file; nothing has to be asked for.
• Each card is audited against the code. When code a skill talks about changes, the audit reads the file against the current code and asks one question: does the code contradict something the skill states? A skill the code contradicts is out of date: its issues are recorded, it is not served, and no further model call is spent on it until the file changes.
• Sessions grade them. A session that invoked a skill is read for whether the skill held; a contradiction the session found takes the skill out the same way. Among skills that do the same thing, the one the sessions confirm is the one served (skills.prefer in the config pins one).

In a session

Nothing changes in how you work. The hooks put the right note in front of the agent at the right moment, and the agent starts at the code it needs instead of searching for it.

• Each request gets the note that fits it, with file:Symbol pointers into the code and a [6 call sites in 3 files] tag on each symbol it names. A local ranking model reads the request with the best lexical candidates and serves up to two notes, only those it scores relevant; when it is missing, notes are ranked by words alone. A note is served once per session, never while stale, and not at all for a one-word turn of conversation. When nothing fits, nothing is served.
• Each file the agent edits brings the rules resting on it, so a trap on that code is in front of the agent as it changes it.
• At the end of each turn one line says what was served: 🧠 thinker: 2 notes this turn (pointing at 2 files, ~7k tokens of code). It does not say "saved": whether the agent acted on a note is known only once the session is assessed.

Measured on real tasks with and without thinker, every model tested used 18% fewer input tokens per task and finished 10% sooner. See the numbers.

The MCP server

The notes reach the agent through the hooks alone. The MCP server offers the agent no tools (since 2026-10-22; the orient, lookup, remember and feedback tools are gone): it carries thinker's own questions and, in a desktop app, its learning queue.

Usage and the holdout

Knowledge-cache benchmarks: one run per arm, different task sets per model. These results do not measure the Find Savings cuts. See the benchmarks or read the method and limitations.

View Report on the local page shows how the cache has been used, for one repository or every repository on the machine: notes served and how, what the sessions did with them, what learning and maintenance cost in tokens, and an estimate of the reads avoided. Where the context itself goes is the Find Savings view.

One number in it is measured rather than estimated. The hooks serve nothing in 15% of prompts, chosen by a hash of the session id and the turn's number, and what every turn cost is recorded from the session's transcript. The holdout comparison compares the prompts that got notes with the ones that had notes withheld, as cost per prompt overall and per model, once twenty prompts stand on each side. This is what the notes do for your own work, on your own repository, by your own agent. holdout in the config changes the share or turns it off.

The local page

The weekly suggestion in your session links to it, and thinker ui opens it from any directory. It is the one place to see and change what thinker does:

The page listens on 127.0.0.1 with a token for that run and stops after half an hour unused. Reports refresh in the background.

Configuration

Everything in .thinker/config.json is optional.

In the environment, THINKER_NO_LEARN=1 turns learning and maintenance off, THINKER_HOOKS=off silences the hooks, THINKER_MCP=off makes the MCP server offer no tools, and THINKER_LLM picks the agent that answers model calls (claude, codex, cursor, gemini, anthropic with ANTHROPIC_API_KEY, or openai: any OpenAI-compatible endpoint named by THINKER_LLM_BASE_URL, with the token in the variable THINKER_LLM_API_KEY_ENV names and the model in THINKER_LLM_MODEL).

Privacy and telemetry

Thinker sends pseudonymous hourly effectiveness metrics (cache hit rate, note count, estimated token savings, and the totals of the holdout comparison: prompt counts and summed tool calls and tokens of prompts with and without notes) to monitor cache quality. They also carry counts for the context proxy (requests through it, tokens the API cleared, errors, and the model ids it saw) and for the choices you make on Find Savings (how many changes were suggested, applied, dismissed or reverted, by kind of part, and the tokens a prompt each measured before and after). These telemetry reports contain no code, note bodies, prompt text, file paths or repository URLs. The only part names in them are your agent's own built-in tools and common shell commands (Grep, Bash:git): never a section title, instruction file, skill name or MCP server name. Note ranking runs on your machine. Learning and verification use your configured model provider. The telemetry opt-out below does not disable those model calls.

# Opt out in your shell environment:
export THINKER_TELEMETRY=off

# Or in .thinker/config.json:
{ "telemetry": false }

Frequently asked questions