🪟 ThinWindow [Claude Code Plugin - Agent Skill - Hooks - Node.js - Measurement]

ThinWindow keeps Claude Code’s context window thin from the first prompt to the next morning. It trims oversized reads and logs while you work, shows what every request carries, and when you come back to an expired session, offers a fresh start from a short brief instead of paying for the old context again. It ships as both a Claude Code plugin and an Agent Skill, and it’s listed in the official Claude Code plugin directory. Zero dependencies, no telemetry, MIT.

View on GitHub Documentation

---

Context is the bill:

A coding agent pays for what it carries more than for what it writes. Three things drive the bill:

• Every request re-sends the whole session. Each file the agent reads, each log it prints and each long answer stays in the conversation and is paid again, from the prompt cache, on every request after it.
• An expired session gets paid for twice. Claude Code keeps a session’s prompt cache for up to an hour. Come back later, and the next prompt writes the whole context again at the cache-write price, many times what reading it from the cache costs.
• The setup rides on every request: the system prompt, the tool definitions, the skill and agent listings, MCP instructions and CLAUDE.md files.

ThinWindow works on all three, at the four moments of a session.

A thin window for the whole session:

• Start: know what every request carries.
  • Once a week per project, when a session’s first request is large, a one-line notice shows what every request starts at and its largest parts.
  • An opt-in thinwindow-minimal profile removes the built-in tools a focused coding session almost never uses.
• During: keep the window thin while you work.
  • Short rules tell the agent to locate before reading, read only the range it needs, cap command output, and write and say only what the task needs.
  • Hooks enforce the expensive part on the tool call itself. A whole-file read of a long file comes back as its head plus a line-numbered outline. Installs, builds and tests run through thinwindow-run, which keeps the full log in a temp file and shows the exit code, the tail and the errors.
• Between sessions: resume without paying twice.
  • A brief of each session is kept at every turn, without calling a model.
  • When you come back to a large session after its cache expired, your first prompt is held once, with what continuing re-writes in tokens and US$ at list price next to a fresh start.
  • /clear then /thinwindow:resume picks up from the brief, and /thinwindow:brief lets the agent write a richer handoff while the cache is still warm.
• After: see where your context went. /thinwindow:report reads your own transcripts on your machine and shows how much context each request re-sends, what expired sessions re-wrote, what your setup carries and whose tool output is re-sent most. Aggregate numbers only, and nothing is sent anywhere.

A skill and a plugin, and why it needs to be both:

These are two layers of the same thing, not two products.

• The Agent Skill is the instruction layer. It carries the rules, kept under 2,000 characters, and thinwindow-run. It’s portable: any agent that supports Agent Skills installs it with npx skills add thinwindow/thinwindow, and agents that read AGENTS.md can paste the same rules in.
• The plugin is the enforcement layer, and it bundles that same skill. Its hooks run at the four moments above: SessionStart for the rules, PreToolUse for the guards, Stop for the brief and the setup notice, and UserPromptSubmit for the cold-resume notice.

The rules are enforced by hooks rather than trusted to the model, because a rule the agent can forget under pressure isn’t a rule. And because the hooks act on the call rather than correcting the agent afterwards, enforcement costs no turn.

Every hook fails open: any error inside ThinWindow lets the call through, and repeating a refused call lets it through too, so an agent can never get stuck on it. THINWINDOW=off disables everything.

Where it works:

• Claude Code (terminal, IDE, the desktop app’s Code tab): everything.
• Cowork:
  • the rules, the read guard and /thinwindow:brief work;
  • the report covers only the current task;
  • briefs don’t carry over between tasks;
  • neither notice shows.
• Chat (claude.ai and the apps): the Agent Skill, which Claude loads when a task needs it, and /thinwindow:brief.

Install:

# From the plugin directory
# (Claude desktop app: Customize → Plugins → Discover → ThinWindow)
claude plugin install thinwindow@anthropic-plugin-directory

# Claude Code, from the repository
/plugin marketplace add thinwindow/thinwindow
/plugin install thinwindow@thinwindow

# Any agent with Agent Skills (Codex, Cursor, Copilot, Gemini CLI, OpenCode)
npx skills add thinwindow/thinwindow

Checked, not assumed:

ThinWindow is checked with a method built to stay cheap as models change.

• Unit tests for every mechanism, in CI on macOS, Linux and Windows.
• Replays of recorded sessions, at no model cost, before anything is built.
• A few targeted agent runs, with their pass criteria written before the first run.
• One validation per release against Claude Code without the plugin.

Before 0.4.0 shipped, its method and pass rules were posted publicly before the first run. Every benchmark task and every resume chain completed with ThinWindow, as they did without it. Starting fresh after the prompt cache expired cost less per completed chain than continuing. The raw rows and the agents’ scrubbed transcripts are public in the repository.

Technical Stack:

• Runtime: Node.js 18+, ESM, zero runtime dependencies. The hooks are local scripts that read a tool call, a prompt or the end of a turn, and return a decision.
• Claude Code integration:
  • four hook events;
  • user-invoked skills that add nothing to the skill listing;
  • bounded, incremental reads of the session transcript;
  • a profile users opt into themselves.
• Distribution: the plugin directory, a Claude Code plugin marketplace, the Agent Skills standard, and a plain AGENTS.md adapter.
• Measurement harness:
  • pinned repositories and hidden verification;
  • one recorded environment per suite;
  • seeded run order and hierarchical intervals;
  • resume chains, and scrubbed transcripts.
• Privacy:
  • no network code: no analytics, no crash reports, no update check;
  • the report prints aggregate numbers only, and a test checks it.

Conclusion:

ThinWindow started as a personal tool to make my own agent sessions cheaper. In 0.4.0 it follows the cost across a whole session instead of a single tool call. The project demonstrates:

• Building against the real cost model of an agent session: context re-sent on every request, re-written after the cache expires, and a setup paid on every turn.
• Using the Claude Code hook API at four moments of a session, with a fail-open design that never blocks a call or a prompt.
• Shipping one codebase as a Claude Code plugin and a portable Agent Skill, so the rules outlive any single harness.
• Measuring with discipline: pre-registered validation, raw data committed, failures kept in, and claims limited to what the data supports.
• Respecting privacy by design: local only, aggregate output, and scrubbed public data.

---