Spend fewer tokens on repeated context.
Thinker works with your coding agent to reduce the context you pay to send again and again: old tool results, oversized instructions and code the agent has already explored.
- Context compression. Clear older tool results so later calls carry less history.
- Instruction file analysis. See which rules earn their place in every prompt, then review cuts to the rest.
- Session profile. Start every session knowing what you are working on, how you want work done and what went wrong before.
The saving adds up across model calls. Your token bill also depends on prompt-cache pricing and rewrites; Thinker reports tokens and costs so you can track the effect on your own work.
npx thinkersh
Connect your agents and keep coding. Installation details.
Install and connect your agents
npx thinkersh
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.
- Connect: restart your agent after installation. Compression runs automatically where supported; the session profile learns as you work.
- Find Savings: review the suggested instructions, skills and tools to shorten or switch off.
- Apply your choices: preview instruction changes as a diff; in the browser, open a pull request to review and merge.
- View Report: track tokens and costs week by week as you keep working.
Keep working as usual. Thinker learns how you work in the background, and periodically suggests instruction and tool changes for you to review. Open thinker ui whenever you want to see savings or reports.
What installation changes
Thinker installs under ~/.thinker and connects your agents in their own settings. Its first report reads the last 30 days of sessions in your five most active repositories; generating that report needs no model call. In the browser, suggestions arrive checked for review. Instruction files and tool settings change only when you apply your choices. Context compression runs automatically where supported.
Each repository's profile starts empty and grows from your sessions. It is stored locally under .thinker/local/. Learning uses your agent's model access. See privacy and telemetry.
Use --no-ui to stay in the terminal. With --yes or no terminal, the installer prints the report.
Stop carrying old tool results into every call.
A file read or test log can stay in context long after the agent used it. Every later model call carries it again. Thinker automatically clears older results in supported agents, reducing the input tokens those calls need.
The three lower bands are the same on every call: 18k tokens here, paid twelve times. The top band is every tool result so far, paid on every call after the one that read it.
In Claude Code, Thinker’s local proxy replaces older results with a short reminder to read them again if needed. It protects the current turn and recent results, and leaves your prompts and the agent’s replies intact. The decision accounts for the prompt-cache rewrite a cut can cause.
Installation enables compression where supported. Claude Desktop clears inside the session; Codex uses the local proxy; Devin uses its own compactor. Agent support varies. Run thinker proxy status to inspect the proxy, or thinker proxy off to disable it. For Claude Desktop, set proxy: { desktop: false } in the machine config.
See the data: sessions and costs → Fewer input tokens do not guarantee a lower bill: cache rewrites and extra reads also count.
Optional: trim a result before it enters context
Claude Code also supports per-tool output trimming with thinker context --output-compression Read --level moderate. Use --level off to disable it. This is off by default and separate from automatic clearing.
src/billing/invoice.py 612 lines · ~7.1k tokens, re-read by the 23 calls after it1 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
This example shows Claude Code’s optional output trimming. Automatic context compression instead clears older results after use.
Keep the instructions that earn their place.
A 4k-token instruction section sent on 40 calls adds 160k input tokens. Open Find Savings with thinker ui to see which sections of AGENTS.md and CLAUDE.md your sessions use, then choose what to shorten or remove.
Review instruction changes in a pull request. The same view also identifies unused skills, MCP servers and tools you can switch off.
| Section | Per prompt | Needed | This week | Wasted | |
|---|---|---|---|---|---|
| Repository layout | 420 | 92% | 1.1M | 88k | |
| Running the tests | 310 | 71% | 0.78M | 0.23M | |
| Release process | 1,460 | 4% | 3.6M | 3.5M | high waste |
| Deploy to staging | 980 | 0% | 2.5M | 2.5M | high waste |
| Legacy API notes | 1,220 | 3% | 3M | 2.9M | high waste |
| Commit conventions | 240 | 58% | 0.6M | 0.25M | |
| Database migrations | 690 | 19% | 1.7M | 1.4M | medium waste |
Pick sections to shorten or remove, review the diff, then open a pull request. How to make a cut.
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.
The sum is what every model call re-reads, times the calls. Here two MCP servers and three sections of AGENTS.md were cut in week 41.
| Part | What it is | Read from |
|---|---|---|
| Instruction files | AGENTS.md, or CLAUDE.md where there is no AGENTS.md, section by section | Claude Code, Codex, Cursor and Gemini CLI sessions |
| Custom tools | The skills listed in every session, MCP servers and plugins, with their descriptions and tool definitions | Claude Code in full; Codex's skill catalog and MCP namespaces; Cursor's MCP servers |
| Built-in tools | The agent's own tool definitions, re-sent with every call | Claude Code |
| Tool outputs | What each tool's results added to the conversation, re-read by every call after them | Claude Code |
One part at a time, as cards. Each instruction section, skill and tool stands beside three measures:
| Measure | What it means |
|---|---|
| Cost | Per prompt: what the part adds to every prompt (one call to the model) that carries it. Needed: the share of those prompts where the agent acted on it. The window total: per prompt × every prompt that carried it. Wasted: that × the prompts that did not need it. |
| Used | A section is applied when a session touched its files, ran its command or read the code it names, read free from the transcript. Relevant and followed come from a model judging a 25% sample of sessions as they end. instructions.value.judge: false disables automatic judging. A skill is read when a session opened it, and the sampled outcome check adds whether sessions that read it kept its rules and how often one broke them without reading it. A tool is used when a session called it. |
| Wasted | What the part cost in the sessions that did not use it (an output: what its results cost after the agent last used them, an estimate from the edits and file calls that followed). High waste from 5% of what its kind costs, medium from 2%. A cut saves that at most: a session that needed the part would go without. For an output it is the size of the problem; compression cuts only what is past its cap. |
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 orgh, the text is written toAGENTS.md(orCLAUDE.md) in your working tree instead, uncommitted, for you to review withgit 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,disabledMcpjsonServersand, for a built-in tool,permissions.denyin.claude/settings.local.json; ordisabledMcpServersin this repository's entry of~/.claude.json, what/mcp disablewrites. Codex:enabled = falsein 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.
Correctness and undo
Every cut removes something the agent might have read. What keeps that from costing you a task:
- Instruction and tool changes are your choice. Review the instruction diff or setting before applying it. Automatic context compression runs separately.
- 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.
- You can undo a cut. Close an unmerged instruction PR or revert a merged change; use Turn back on for anything switched off. Recent activity tracks your changes. 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.
Start every session oriented.
Thinker learns how you work in each repository and puts that into the first prompt of every session: what you are in the middle of, how you want work done and answers given, what went wrong before and the recent bugs. The agent starts knowing the person it works for, instead of learning it again through corrections.
What the profile is
Five short sections, about 1,500 tokens, every line resting on observations from your own sessions and counted in sessions:
| Section | What it says |
|---|---|
| Working on | The lines of work you are in the middle of, and where each stands by your last reaction |
| How this person works | How you want work done and answers given: stated preferences first, then corrections repeated across sessions |
| What went wrong before | "When doing X: avoid Y", with your own words quoted, and what you then accepted instead |
| Recent bugs | The symptom, the cause where it was told, and whether the fix was accepted |
| Skills | Which skills are run here and by whom, what each is used for, and how it went by your reactions |
It is learned from a session's prompts and the agent's answers alone, never its tool calls or their results. The outcome of each exchange is read from your next prompt: the agent's own "done" is a claim, and a correction is what counts. The block is headed as learned context, not instructions, and goes in again after a compaction, since a compaction summary keeps none of it.
Keeping it current
- Each session is read once, when it ends, through the agent's own login: a model records what was asked, what the agent says it did and how you reacted, and the profile is patched with it. A single session on new work becomes a Working on line; the next session on the same work updates it.
- The code keeps it honest. Every line cites the observations behind it; a line nothing in the last 60 days supports leaves by itself, a workstream not seen for three weeks and a bug not seen for two leave too, and a rule needs two sessions or one statement in your own words.
- Once a month the profile is compiled again from nothing, so wording the patches have carried for weeks is derived again from the observations.
- The spend is bounded. One model call per session plus the patch, under a daily token cap (
maintain.dailyTokens).
.thinker/local/profile/, which git ignores. thinker profile show prints what a session is shown; --why the evidence behind each line.
In a session
Nothing changes in how you work. The context clearing runs through a local proxy (or inside the Claude desktop app's own session), and the profile goes into the first prompt.
- Older tool results are cleared out of the requests the agent sends once a conversation grows, when the saving repays the prompt-cache rewrite it costs; recent results and the current turn are kept.
- Periodic summaries say what the clearing saved; the status line under the prompt in Claude Code keeps the figure on screen.
The MCP server
The profile reaches the agent through the hooks alone. The MCP server offers the agent no tools: it carries thinker's own questions and, in a desktop app, its learning queue.
Usage and the holdout
View Report on the local page shows what a session costs here week by week and what the clearing saved, measured: the proxy counts what it left out of each prompt. thinker usage prints the requests, sessions and what learning spent; thinker savings the figure the status line carries.
The profile is measured too. 15% of sessions see no profile, chosen by a hash of the session id, and every observation learned from a session carries which side it was on. thinker profile holdout compares corrections and redirects per session on each side, beside what each side's sessions cost; fewer than twenty sessions a side is too few to read.
Supported agents
Thinker works inside the tools you already use. Five agents are wired once per machine in their own settings; four more get an extension or hook file in the checkout.
| Agent | The profile | Context clearing | Wiring |
|---|---|---|---|
| Claude Code, and the Claude desktop app's Code tab | First prompt, and after a compaction | Automatic: the proxy, or the mod inside the desktop app | Machine-wide |
| Codex CLI and the Codex desktop app | First prompt | Through the proxy's Codex route | Machine-wide |
| Gemini CLI | First prompt | No: Google's API only | Machine-wide |
| Cursor | With the first prompt; the CLI one tool call late | No: calls go through Cursor's servers | Machine-wide, plus a rule in the checkout |
| Devin CLI and Devin Desktop's local agent | First prompt | Devin's own compactor, set to the proxy's trigger | Machine-wide |
| Pi | Extension | Automatic: the proxy | The checkout |
| Windsurf Cascade | No: its hooks only record | No: Windsurf's servers | The checkout |
| GitHub Copilot CLI | With the first tool result | By hand, with your own Anthropic key | The checkout |
| OpenCode | Plugin | Automatic (opencode.json) | 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.
Where each agent is wired
- Claude Code: hooks in
~/.claude/settings.json, the MCP server in~/.claude.json.UserPromptSubmitadds the profile to the first prompt,StopandSessionEndread the session once in the background. - Codex CLI: hooks in
~/.codex/hooks.json, the MCP server in~/.codex/config.toml, where the project and the hooks are also marked trusted so Codex asks nothing before running them. The desktop app reads the same file. - Gemini CLI: prompt-time context and the MCP server in
~/.gemini/settings.json. Gemini Code Assist's agent mode reads the same configuration. - Cursor: hooks in
~/.cursor/hooks.json, the MCP server in~/.cursor/mcp.json(approved by setup), and an always-applied rule in the checkout. Cursor's CLI prompt hook cannot add context, so there the profile is handed over with the first tool result. - Devin: hooks in
~/.config/devin/config.json, the MCP server in~/.config/devin/mcp_config.json, and one permission entry so the background subagent that does the learning may call thinker's own tool. The same files serve the CLI and Devin Desktop's local agent. Devin refuses to run in a workspace you have not trusted, so rundevinonce in the repository and accept the prompt. - Pi, Windsurf Cascade, Copilot CLI, OpenCode: nothing machine-wide. The installer, given
--clients pi,windsurf,copilot,opencode, writes an extension, a hook file or a rule. Restart the host agent afterwards.
Setting up Devin
The installer finds Devin on its own, so there is usually nothing to do beyond npx thinkersh and restarting Devin. If you installed thinker before Devin, or skipped it, wire it by hand:
thinker connect --clients devin
That writes the hooks and the MCP server into Devin's own configuration, adds the one permission its background subagent needs to do the learning, and sets Devin's compaction threshold to the same point thinker's proxy clears at. The CLI and Devin Desktop's local agent read the same files, so both are covered at once.
If Devin refuses to start with Refusing to run in an untrusted workspace, that is Devin's own check, not thinker's, and it happens before any hook runs, so you would see no notes and no error. Run devin once in that repository, accept the prompt, and quit.
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:
| View | What it does |
|---|---|
| Find Savings | See context cost and use over 7 or 30 days, for one repository or all. Apply cuts, and follow them under Recent activity, whose badge counts what still needs you. |
| View Report | Track the average tokens a prompt (one call to the model) or its list-price cost over six weeks, by context part, model and token type. Review your changes and the cache's savings below. |
| Recent activity | Every change you made, newest first, with what came of it: Retry a failed one, Close PR on a pending one, Revert any of them. |
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.
| Key | Effect |
|---|---|
learn | {"sessions": false} stops distilling sessions; pull requests and re-verification go on |
maintain | enabled, dailyTokens (10,000,000 with a Haiku-class distillation model, 1,000,000 otherwise), verifyEveryDays (3), verifyPerRun (50), verifyServedDays (3), deleteUnusedDays (14), phrasePerRun (8); off by default: prs (with prsPerRun, 3), docs (with docsPerRun, 3), skills, dedupe |
instructions | {"value": {"judge": true, "share": 0.25}} has a model judge a sample of sessions as they end, for the Context page's relevant and followed |
diet | Tool output compression, written from Find Savings: {"tools": {"Read": "moderate", "Bash": "moderate"}} |
harness | enabled (switching skills and tools off writes the agent's settings; the page turns it on when you switch one off), builtinTools (offer Claude Code's built-in tools too) |
archive | kinds and unservedDays (30), or false |
holdout | The share of sessions served nothing (0.15; 0 or false: none) |
learn.profile | false keeps the session profile off in this repository; holdout (0.15) is the share of sessions it is held out of |
snippets, notice | false: no code behind the pointers; no end-of-turn line |
distillModel, verifyModel | The model for each kind of call |
telemetry | false: no metrics sent |
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 (requests, sessions, the profile's two arms as counts, and what the clearing saved) to monitor 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
Where is my data stored? Does anything leave my machine?
Everything Thinker learns stays on your machine. The profile of how you work in a repository is under its .thinker/local/, which git ignores; there is no team sharing or sync. .thinker/config.json holds the configuration. Per machine, ~/.thinker/ holds the installed app, the usage log, the savings ledger and the proxy's records.
Network activity includes:
- Model calls go to the provider you already use for your agent. Reading a session into the profile runs through your agent's own login (
claude, or an Anthropic API key), or, in a desktop app, through the app's own session. A session is read from its prompts and the agent's answers alone, never its tool calls or their results. - Telemetry is counts only. An hourly report carries numbers: requests, sessions, what the clearing saved, the profile's two arms, token totals, what you compressed or switched off and what it measured as saved, with an install id and a hashed device id. It contains no code, profile text, prompt text, file paths or repository URLs.
THINKER_TELEMETRY=offor{ "telemetry": false }in the config stops it. - The ranking model is downloaded once at install (about 23 MB) and runs on your machine.
The local page of thinker ui listens on 127.0.0.1 only.
A repository with sensitive content can be turned off with thinker disable inside it. Thinker then does nothing there, in any clone or worktree: the hooks and the MCP server serve nothing, no session is read, and nothing is written into it. thinker enable turns it back on.
Where do the context savings come from? Why does a short section matter?
Context carried across 40 model calls is counted 40 times. Thinker addresses that repetition in two places: clearing old tool results and shortening instructions you review; the profile spends about 1,500 tokens a session to spare the corrections that cost many more. reusing knowledge from previous sessions.
Token reductions are not dollar savings one for one. Cached input has a different price, and a cut can cause a cache rewrite. Track both tokens and costs in View Report.
Will my agent miss something I cut?
It can, which is why instruction changes need your review. Find Savings helps you assess them:
- Use is measured first. A section is applied when a session touched its files, ran its command or read the code it names; a judge can add relevant and followed. Only a part used in under half the sessions is flagged, and high waste means large and used in almost none. Start there.
- Compress keeps the rules. The model 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. If a section holds rules the agent must follow, compress it rather than remove it.
- A switched-off skill still runs when you type
/name; only its listing leaves the context. An MCP server or plugin is off for new sessions in this repository, not removed. - Afterwards, followed and missed on the cards show whether sessions kept a rule they no longer read. Each cut has an undo path (below).
No benchmark is claimed for the cuts yet: the savings are tokens the sessions would not have read, measured on your sessions, and the followed and missed counts are the check on correctness.
Can compressing tool outputs break what the agent does?
Clearing removes older results from the context the model reads. It does not change the files or undo the tool’s work. The agent may need to read something again; those extra calls can reduce the saving.
Thinker protects recent results and the current turn. A cleared result carries a reminder to read it again when needed. See context compression for controls and the session comparisons for costs and limitations.
What does a cut change on my machine, and how do I undo it?
| Cut | What is written | Undo |
|---|---|---|
| Compress or remove a section | A branch thinker/context-… pushed to the origin and a pull request against the default branch; the working tree is untouched. Without GitHub or gh: the new text of AGENTS.md (or CLAUDE.md) in your working tree, uncommitted. The preview is kept under .thinker/state/ | Close the unmerged PR, revert a merged change, or restore the uncommitted file |
| Switch a skill, plugin, MCP server or built-in tool off | One key in the agent's own settings for this repository: .claude/settings.local.json or this repository's entry in ~/.claude.json; the checkout's .codex/config.toml or, for a Codex skill, ~/.codex/config.toml; ~/.cursor/mcp.json. Each file is backed up first under ~/.thinker/state/harness-backups/ | Turn back on |
Viewing the report changes no instructions or agent settings. Opening an instruction pull request commits and pushes only the change you reviewed.
What does Thinker do in a session?
Two things. It clears what the agent has finished with out of its context: older tool results are replaced in the requests the agent sends, so every later call reads a shorter prompt. That is where the cost is, and it is measured. And it puts a profile of how you work in this repository into the session's first prompt, and again after a compaction.
Where does the profile come from? Can I build it up front?
From your own sessions, and from nothing else. When a session ends, a model reads its prompts and the agent's answers, records what was asked and how you reacted, and patches the profile. thinker profile rebuild --days 30 reads the last month's sessions at once; there is no other build step.
- The spend is bounded. One model call per session plus the patch, through your agent's login, under a daily token cap (
maintain.dailyTokensin.thinker/config.json). - You can stop it.
{ "learn": { "profile": false } }in the config stops the profile in a repository;THINKER_NO_LEARN=1stops all learning.
How can I tell if Thinker is helping my agents?
- The savings are measured. The status line, the cards and
thinker savingssay what the clearing saved today and over the whole log, at list prices; View Report shows it week by week beside what a session costs. - The Find Savings view, and the weekly suggestion drawn from it, show where your agents' context goes and how often sessions acted on each part, so what you cut is measured on your own sessions.
- The profile has a holdout. 15% of sessions see no profile, and
thinker profile holdoutcompares corrections and redirects per session on each side. Fewer than twenty sessions a side is too few to read.