thinker / docs

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.

  1. Context compression. Clear older tool results so later calls carry less history.
  2. Instruction file analysis. See which rules earn their place in every prompt, then review cuts to the rest.
  3. 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.

  1. Connect: restart your agent after installation. Compression runs automatically where supported; the session profile learns as you work.
  2. Find Savings: review the suggested instructions, skills and tools to shorten or switch off.
  3. Apply your choices: preview instruction changes as a diff; in the browser, open a pull request to review and merge.
  4. 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.

Context compression

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.

What one session sends, call by call example 12 model calls · 377k input tokens in all, 57% of them the fixed part
Instruction filesCustom toolsBuilt-in toolsTool outputs so far
Example: the context sent on each model call of one sessionTwelve columns, one per model call. The lowest three bands, the instruction files, custom tools and built-in tools, are the same 18k tokens on every call; the tool outputs above them grow from nothing to 25k as results accumulate. The session sends 377k input tokens in all.12k24k36k48kCall 1 · Instruction files: 6.4k tokensCall 1 · Custom tools: 9.8k tokensCall 1 · Built-in tools: 1.8k tokens18k1Call 2 · Instruction files: 6.4k tokensCall 2 · Custom tools: 9.8k tokensCall 2 · Built-in tools: 1.8k tokensCall 2 · Tool outputs so far: 1.8k tokens20k2Call 3 · Instruction files: 6.4k tokensCall 3 · Custom tools: 9.8k tokensCall 3 · Built-in tools: 1.8k tokensCall 3 · Tool outputs so far: 2.6k tokens21k3Call 4 · Instruction files: 6.4k tokensCall 4 · Custom tools: 9.8k tokensCall 4 · Built-in tools: 1.8k tokensCall 4 · Tool outputs so far: 9.7k tokens28k4Call 5 · Instruction files: 6.4k tokensCall 5 · Custom tools: 9.8k tokensCall 5 · Built-in tools: 1.8k tokensCall 5 · Tool outputs so far: 10.9k tokens29k5Call 6 · Instruction files: 6.4k tokensCall 6 · Custom tools: 9.8k tokensCall 6 · Built-in tools: 1.8k tokensCall 6 · Tool outputs so far: 12.1k tokens30k6Call 7 · Instruction files: 6.4k tokensCall 7 · Custom tools: 9.8k tokensCall 7 · Built-in tools: 1.8k tokensCall 7 · Tool outputs so far: 14.4k tokens32k7Call 8 · Instruction files: 6.4k tokensCall 8 · Custom tools: 9.8k tokensCall 8 · Built-in tools: 1.8k tokensCall 8 · Tool outputs so far: 15k tokens33k8Call 9 · Instruction files: 6.4k tokensCall 9 · Custom tools: 9.8k tokensCall 9 · Built-in tools: 1.8k tokensCall 9 · Tool outputs so far: 22.3k tokens40k9Call 10 · Instruction files: 6.4k tokensCall 10 · Custom tools: 9.8k tokensCall 10 · Built-in tools: 1.8k tokensCall 10 · Tool outputs so far: 23.1k tokens41k10Call 11 · Instruction files: 6.4k tokensCall 11 · Custom tools: 9.8k tokensCall 11 · Built-in tools: 1.8k tokensCall 11 · Tool outputs so far: 24k tokens42k11Call 12 · Instruction files: 6.4k tokensCall 12 · Custom tools: 9.8k tokensCall 12 · Built-in tools: 1.8k tokensCall 12 · Tool outputs so far: 25.2k tokens43k12

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.

Optional output trimming, before and after example
Read src/billing/invoice.py 612 lines · ~7.1k tokens, re-read by the 23 calls after it
  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)
The same result, moderate compression 54 lines · ~0.9k tokens
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.

Instruction file analysis

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.

Find Savings: see which instructions earn their place example 48 sessions, 2,500 prompts · 5,320 tokens per call · 13.3M input tokens on the file, 10.9M of it wasted3 sections picked · 3,660 tokens per call, 9.2M this weekApply
SectionPer promptNeededThis weekWasted
Repository layout42092%1.1M88k
Running the tests31071%0.78M0.23M
Release process1,4604%3.6M3.5Mhigh waste
Deploy to staging9800%2.5M2.5Mhigh waste
Legacy API notes1,2203%3M2.9Mhigh waste
Commit conventions24058%0.6M0.25M
Database migrations69019%1.7M1.4Mmedium 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.

Input tokens a session, by week example
Instruction filesCustom toolsBuilt-in toolsTool outputs
Example: input tokens a session by week, stacked by partSix weekly columns; the sum falls from about 790k to 520k tokens a session after the cuts in week 41.200k400k600k800kW37 · Instruction files: 160k tokens a sessionW37 · Custom tools: 210k tokens a sessionW37 · Built-in tools: 60k tokens a sessionW37 · Tool outputs: 300k tokens a session730kW37W38 · Instruction files: 150k tokens a sessionW38 · Custom tools: 220k tokens a sessionW38 · Built-in tools: 60k tokens a sessionW38 · Tool outputs: 340k tokens a session770kW38W39 · Instruction files: 150k tokens a sessionW39 · Custom tools: 230k tokens a sessionW39 · Built-in tools: 60k tokens a sessionW39 · Tool outputs: 310k tokens a session750kW39W40 · Instruction files: 140k tokens a sessionW40 · Custom tools: 230k tokens a sessionW40 · Built-in tools: 60k tokens a sessionW40 · Tool outputs: 360k tokens a session790kW40W41 · Instruction files: 95k tokens a sessionW41 · Custom tools: 120k tokens a sessionW41 · Built-in tools: 60k tokens a sessionW41 · Tool outputs: 280k tokens a session555kW41W42 · Instruction files: 90k tokens a sessionW42 · Custom tools: 110k tokens a sessionW42 · Built-in tools: 60k tokens a sessionW42 · Tool outputs: 260k tokens a session520kW42

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.

PartWhat it isRead from
Instruction filesAGENTS.md, or CLAUDE.md where there is no AGENTS.md, section by sectionClaude Code, Codex, Cursor and Gemini CLI sessions
Custom toolsThe skills listed in every session, MCP servers and plugins, with their descriptions and tool definitionsClaude Code in full; Codex's skill catalog and MCP namespaces; Cursor's MCP servers
Built-in toolsThe agent's own tool definitions, re-sent with every callClaude Code
Tool outputsWhat each tool's results added to the conversation, re-read by every call after themClaude Code

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

MeasureWhat it means
CostPer 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.
UsedA 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.
WastedWhat 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 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.

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.

The session profile

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:

SectionWhat it says
Working onThe lines of work you are in the middle of, and where each stands by your last reaction
How this person worksHow 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 bugsThe symptom, the cause where it was told, and whether the fix was accepted
SkillsWhich 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).
Local by default. The profile lives in .thinker/local/profile/, which git ignores. thinker profile show prints what a session is shown; --why the evidence behind each line.
Efficient coding

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.

Measure it yourself

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.

Reference

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.

AgentThe profileContext clearingWiring
Claude Code, and the Claude desktop app's Code tabFirst prompt, and after a compactionAutomatic: the proxy, or the mod inside the desktop appMachine-wide
Codex CLI and the Codex desktop appFirst promptThrough the proxy's Codex routeMachine-wide
Gemini CLIFirst promptNo: Google's API onlyMachine-wide
CursorWith the first prompt; the CLI one tool call lateNo: calls go through Cursor's serversMachine-wide, plus a rule in the checkout
Devin CLI and Devin Desktop's local agentFirst promptDevin's own compactor, set to the proxy's triggerMachine-wide
PiExtensionAutomatic: the proxyThe checkout
Windsurf CascadeNo: its hooks only recordNo: Windsurf's serversThe checkout
GitHub Copilot CLIWith the first tool resultBy hand, with your own Anthropic keyThe checkout
OpenCodePluginAutomatic (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. UserPromptSubmit adds the profile to the first prompt, Stop and SessionEnd read 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 run devin once 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:

ViewWhat it does
Find SavingsSee 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 ReportTrack 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 activityEvery 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.

KeyEffect
learn{"sessions": false} stops distilling sessions; pull requests and re-verification go on
maintainenabled, 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
dietTool output compression, written from Find Savings: {"tools": {"Read": "moderate", "Bash": "moderate"}}
harnessenabled (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)
archivekinds and unservedDays (30), or false
holdoutThe share of sessions served nothing (0.15; 0 or false: none)
learn.profilefalse keeps the session profile off in this repository; holdout (0.15) is the share of sessions it is held out of
snippets, noticefalse: no code behind the pointers; no end-of-turn line
distillModel, verifyModelThe model for each kind of call
telemetryfalse: 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 }
FAQ

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=off or { "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.

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?

CutWhat is writtenUndo
Compress or remove a sectionA 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 offOne 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.dailyTokens in .thinker/config.json).
  • You can stop it. { "learn": { "profile": false } } in the config stops the profile in a repository; THINKER_NO_LEARN=1 stops all learning.

How can I tell if Thinker is helping my agents?

  • The savings are measured. The status line, the cards and thinker savings say 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 holdout compares corrections and redirects per session on each side. Fewer than twenty sessions a side is too few to read.