context-carwash 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.8
+
+- Shorter, clearer README.
+
+## 0.1.7
+
+- `carwash doctor` checks that the Node Carwash runs with is still there, and says how to fix it if not. Removing that Node, for example an old version in nvm, stops the meter and `/wash` until install is run again. The installer now says which Node that is.
+- Clearer wording on when Carwash goes online, and a reminder to look over `doctor` output before posting it in a public issue.
+
 ## 0.1.6
 
 - Update notices: once a day, a new session checks npm in the background. A line under the meter says when a newer version is out, or when the version you have carries a warning. `CARWASH_NO_UPDATE_CHECK=1` turns it off.

package/README.md

@@ -1,34 +1,22 @@
 # Context Carwash
 
-A small, local-first utility for Claude Code.
+Context Carwash adds a line to Claude Code in your terminal that:
 
-- **Meter:** a quiet estimate of the active context window in the status line.
-- **Wash:** when you ask, Claude writes a short handoff brief, and your next `/clear` starts a fresh session that begins with it.
-
-Nothing happens automatically, and nothing about you is ever sent. Carwash goes online in two ways: once a day it reads its own public page on npm to see if a newer version is out (you can turn that off), and `carwash stats --share` sends anonymous totals if you run it and say yes.
-
-**Status:** pre-release. The meter and the typed `/wash` command work today. Clickable links in the status line and the one-step restart are not built yet. See [plan-3.md](plan-3.md) for the design.
+1. Shows the current conversation's context size.
+2. Lets you compress your context and start a new session without losing the important details.
 
 ## Install
 
 Requires Node 18 or later.
 
 ```sh
-npx context-carwash preview     # sample meters in your terminal, nothing installed
+npx context-carwash preview     # see sample meters, nothing installed
 npx context-carwash install     # lists what it will change, then asks
 ```
 
-To update later, run `npx context-carwash@latest install`. Waiting briefs are kept. If npx reruns an older copy it downloaded before, the installer notices that npm has a newer version and installs that one instead.
-
-You do not have to watch for new versions. Once a day, when a session starts, Carwash checks npm in the background. If a newer version is out, or the version you have has a known problem, a line under the meter says so, with the command to update. `/wash help` shows the version you have.
+Then start a new Claude Code session. To update later, run `npx context-carwash@latest install`. You don't need to watch for updates: a line under the meter tells you when there's a new version.
 
-The installer copies itself to `~/.carwash/app` and makes three changes to Claude Code, all listed before you confirm:
-
-- **Status line** in `~/.claude/settings.json`. If you already have one, yours keeps running and the meter is added after it.
-- **Three hooks** in the same file, added after any hooks you already have. They are how `/wash` saves a brief and how a fresh session receives it.
-- **The `/wash` command** at `~/.claude/skills/wash`.
-
-Start a new Claude Code session afterwards. The first one explains the meter and `/wash` in a short note, shown once.
+The installer adds a status line and three hooks to `~/.claude/settings.json`, after anything you already have there, and adds the `/wash` command at `~/.claude/skills/wash`.
 
 ## The meter
 
@@ -36,22 +24,14 @@ Start a new Claude Code session afterwards. The first one explains the meter and
 session context ~136k  [██████████░░░░░]  /wash to compress & save context, then /clear keeps compressed context
 ```
 
-The number is how many tokens the conversation is using. It comes from Claude Code and is an estimate. The bar shows how close that is to the most the model's context window holds, and changes colour as it fills. From three quarters on, the meter also says so in words:
-
-```text
-session context ~150k  [███████████░░░░]  getting full · /wash to compress & save context, then /clear keeps compressed context
-```
-
-Narrower windows show less. The sentence shortens first: `/wash to compress & save context, then /clear` fits about half a Mac screen, `/wash to compress, then /clear` fits an 80-column window, and the narrowest windows show `/wash to compress`. Then the bar goes.
+The number is how many tokens the conversation is using, as estimated by Claude Code. The bar shows how full the context window is and changes colour as it fills. In narrow windows the text gets shorter. The meter never does anything on its own.
 
-A full meter is information. It never triggers anything.
+## /wash
 
-## Starting fresh with a brief
+1. Type `/wash`. Claude writes a short brief: what you're doing, where things stand, and what to do next. The status line changes to `Brief ready ✓`.
+2. Type `/clear`. The new session starts with that brief already loaded.
 
-1. Type `/wash` (or `/wash light`, `/wash detailed`). Claude replies with a brief: what you are doing, where things stand, and what to do next. The status line changes to `Brief ready ✓`.
-2. Type `/clear`. The new session starts with that brief already loaded, and says so: `Loaded your Carwash brief (mid ~1.1k, 2m ago), down from ~136k in the old session.`
-
-Your old conversation is not deleted. It stays in `/resume`.
+Your old conversation stays in `/resume`.
 
 | Command | What it does |
 |---|---|
@@ -61,21 +41,15 @@ Your old conversation is not deleted. It stays in `/resume`.
 | `/wash detailed` | Adds rationale, history, test results, risks, a step checklist |
 | `/wash discard` | Drop the brief. `/clear` is a normal clear again |
 | `/wash load [id]` | Make a waiting brief the one your next `/clear` uses |
-| `/wash stats` | How much context your washes have saved (see below) |
-| `/wash help` | Explain the meter and these options, with this session's size limits |
-
-Each level has a size limit: the most tokens its brief may take, worked out from what the conversation is using (a hundredth for `light`, three hundredths for `mid`, a tenth for `detailed`). `/wash help` shows the limits for the session you are in.
-
-Words after the level are passed to Claude as a note on what to emphasise: `/wash mid focus on the failing test`.
+| `/wash stats` | How much context your washes have saved |
+| `/wash help` | Explain the meter and these options |
 
-Things worth knowing:
-
-- **A `/clear` with no brief ready is a normal clear.** Carwash only acts when you have asked for a brief in that terminal.
-- **Writing a brief costs tokens.** It is an ordinary Claude reply. `help`, `discard` and `load` cost nothing: they never reach Claude.
-- **The cap is a ceiling, not a target.** A brief is as short as it can be. If one comes out over its cap, Claude is asked to shorten it, up to twice. If it is still over, it is kept and the message says so.
-- **Sizes are estimates.** The brief's size is worked out from its length. It covers the brief alone, so the meter in the new session reads higher: it also counts Claude Code's own baseline.
-- **Closed the terminal before clearing?** Start `claude` in the same folder. If exactly one brief is waiting for that folder, it is under 12 hours old, and the session that wrote it has ended, it is loaded. If there is any doubt about which brief is meant, nothing is loaded and you are shown what is waiting, with the `/wash load <id>` to use.
-- **Briefs expire after 48 hours.** A delivered brief is kept for 24 hours in case you want it again (`/wash load <id>`), then deleted.
+- Words after the level tell Claude what to focus on: `/wash mid focus on the failing test`.
+- A `/clear` with no brief ready is a normal clear.
+- Writing a brief is an ordinary Claude reply, so it uses tokens. `help`, `discard` and `load` don't.
+- Each level has a size limit based on how big the conversation is. `/wash help` shows them.
+- Closed the terminal before `/clear`? Start `claude` in the same folder and the brief loads. If more than one is waiting, you're shown which ones, with the `/wash load <id>` to pick one.
+- Briefs expire after 48 hours.
 
 ## Stats
 
@@ -94,19 +68,9 @@ Carwash stats, since 3 Oct 2026 (12 days)
   Net saved                   ~20M tokens
 ```
 
-`/wash stats` shows the same inside Claude Code, at no cost.
-
-How it is worked out: every request to Claude carries the whole conversation, and a single prompt can make many requests while Claude uses tools. After a wash, each request in the fresh session starts from the brief instead of the old conversation. Claude Code's transcript of that session records the size of every request, so Carwash counts the requests and multiplies by the gap. Nothing is assumed about how long you would have kept going: only requests you actually made count. Counting stops where the old session would have compacted on its own.
-
-Claude caches repeated context and charges about a tenth for it, so in money terms the saving is roughly a tenth of these numbers. The brief cost counts every brief written, used or not.
+Every request to Claude re-sends the whole conversation. After a wash, each request starts from the small brief instead, so Carwash counts the requests you actually made and adds up the difference. Claude charges about a tenth for repeated context, so the money saved is roughly a tenth of these numbers. `/wash stats` shows the same inside Claude Code.
 
-### Sharing your stats
-
-```sh
-npx context-carwash stats --share
-```
-
-This shows every field it would send, and sends only if you say yes. It sends totals to a Google Form: a random share id made for sharing only (so sharing again replaces your last share), the Carwash version, your operating system, days since your first brief, and the numbers above. No names, folders, projects, prompts or briefs. You are not signed in to send it.
+`npx context-carwash stats --share` sends your anonymous totals, but only after showing you exactly what it will send and you say yes.
 
 ## Something not working?
 
@@ -114,15 +78,11 @@ This shows every field it would send, and sends only if you say yes. It sends to
 npx context-carwash doctor
 ```
 
-This checks that the status line, hooks and `/wash` command are still in place, and shows your Carwash, Node, Claude Code and operating system versions, the newest version on npm, and the last few errors. Paste it into a [new issue](https://github.com/Spobi/context-carwash/issues/new).
-
-If a hook fails, the status line shows `Carwash hit an error` until you run `doctor`.
+This checks that everything is still installed and working, and shows your versions and recent errors. Paste the output into a [new issue](https://github.com/Spobi/context-carwash/issues/new). Issues are public, and errors can include folder names, so look it over first.
 
 ## Where things are kept
 
-Briefs are stored in `~/.carwash`, readable only by you, and never inside your project. So is the stats ledger (`~/.carwash/stats`): one small file per brief with its size, its level, and which fresh sessions it went to, but never the brief or your prompts. Nothing about you is uploaded, and there is no telemetry. Once a day, a new session reads Carwash's public page on npm: the newest version, and any warning about the one you have. That is a download, like opening a web page, and it sends nothing about you, your projects or your use. The answer is kept in `~/.carwash/notice.json`. `install` and `doctor` read the same page when you run them. Set `CARWASH_NO_UPDATE_CHECK=1` to turn all of this off. `stats --share` sends only when you run it and say yes.
-
-If a hook fails it stays silent, writes the error to `~/.carwash/errors.log`, and the status line says so.
+Briefs, stats and error logs are kept in `~/.carwash`, readable only by you. Nothing about you is uploaded. Once a day Carwash checks npm for a newer version. Set `CARWASH_NO_UPDATE_CHECK=1` to turn that off.
 
 ## Uninstall
 
@@ -132,12 +92,6 @@ npx context-carwash uninstall
 
 This puts `settings.json` back exactly as it was. If you have edited the file since installing, it removes only Carwash's own status line and hooks and keeps your edits. It then removes the `/wash` command and deletes `~/.carwash`, including any briefs still waiting and your stats.
 
-## Limitations
-
-- Terminal.app cannot click links. When clickable links arrive for other terminals, Terminal.app will keep showing the command to type.
-- The status line re-runs every 5 seconds while a session is open, so it stays correct after `/wash discard` and `/wash load`. Each run reads a few small local files. If your own status line sets a refresh interval, yours is kept.
-- Claude Code shows `help`, `discard`, `load`, and mistyped arguments under the heading "operation blocked by hook". That is Carwash answering the command itself instead of sending it to Claude.
-
 ## Platforms
 
 Developed and tested on macOS. Automated tests also run on Linux and Windows; neither has been tried by hand yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-carwash",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "A quiet context meter and deliberate fresh-session handoff for Claude Code.",
   "license": "MIT",
   "repository": {

package/src/install/doctor.mjs

@@ -6,7 +6,7 @@ import { readJson } from '../files.mjs';
 import { errorLogPath, errorsSeenPath, installRecordPath, settingsPath, skillDir } from '../paths.mjs';
 import { refreshLedger, totals } from '../stats/ledger.mjs';
 import { readyRecords } from '../wash/store.mjs';
-import { isCarwashCommand, isCarwashHook } from './install.mjs';
+import { commandProgram, isCarwashCommand, isCarwashHook } from './install.mjs';
 import { UPDATE_COMMAND } from './notice.mjs';
 import { readSettings, resolveSettingsFile } from './settings.mjs';
 import { isNewer } from './update.mjs';
@@ -59,7 +59,19 @@ function settingsCheck(env) {
   }
   const groups = (event) => (Array.isArray(data?.hooks?.[event]) ? data.hooks[event] : []);
   const hooks = Object.fromEntries(HOOK_EVENTS.map((event) => [event, groups(event).some((group) => Array.isArray(group?.hooks) && group.hooks.some((hook) => isCarwashHook(hook?.command)))]));
-  return { readable: true, statusLine: isCarwashCommand(data?.statusLine?.command), hooks };
+  const hookCommands = HOOK_EVENTS.flatMap((event) => groups(event).flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks.map((hook) => hook?.command) : [])));
+  const ours = [data?.statusLine?.command, ...hookCommands].filter((command) => isCarwashCommand(command) || isCarwashHook(command));
+  return { readable: true, statusLine: isCarwashCommand(data?.statusLine?.command), hooks, nodes: [...new Set(ours.map(commandProgram).filter(Boolean))] };
+}
+
+// The Node that Carwash's commands start. Install writes its path into the
+// settings, so if that Node is removed later (version managers such as nvm
+// keep one folder per version), nothing of Carwash runs, not even the part
+// that would log an error. Plain `node` (Windows) is looked up on PATH.
+function nodeRow(nodes) {
+  const missing = nodes.find((node) => /[\\/]/.test(node) && !existsSync(node));
+  if (missing) return `MISSING: ${tilde(missing)} · to fix: ${UPDATE_COMMAND}`;
+  return nodes.length ? `ok (${nodes.map(tilde).join(', ')})` : null;
 }
 
 const date = (iso) => {
@@ -100,6 +112,8 @@ export function doctorReport({ env = process.env, now = Date.now(), running, new
     } else {
       out.push(row('Status line', yes(check.statusLine)));
       out.push(row('Hooks', HOOK_EVENTS.map((event) => `${event} ${yes(check.hooks[event])}`).join(' · ')));
+      const node = nodeRow(check.nodes);
+      if (node) out.push(row('Node for Carwash', node));
     }
     out.push(row('/wash command', yes(existsSync(join(skillDir(env), 'SKILL.md')))));
     let waiting = '?';
@@ -123,6 +137,7 @@ export function doctorReport({ env = process.env, now = Date.now(), running, new
   if (!errors.length) out.push(`Errors: none logged.`);
   else out.push(`Last ${errors.length === 1 ? 'error' : `${errors.length} errors`} (from ${tilde(errorLogPath(env))}):`, '', ...errors.map((entry) => entry.replace(/^/gm, '  ')));
   out.push('', `Something wrong? Open an issue and paste everything above: ${ISSUES_URL}`);
+  out.push('Issues are public, so look it over first: error details can include folder names.');
   return out.join('\n');
 }
 

package/src/install/install.mjs

@@ -69,6 +69,16 @@ export function commandFor(verb, { nodePath, scriptPath, platform = process.plat
 
 export const statusLineCommand = (options) => commandFor('statusline', options);
 
+// The program a command from commandFor starts, with its quoting undone: the
+// Node it was installed with, or plain `node` on Windows.
+export function commandProgram(command) {
+  const word = /^\s*('(?:[^']|'\\'')*'|"[^"]*"|[^\s'"]+)/.exec(String(command ?? ''))?.[1];
+  if (!word) return null;
+  if (word.startsWith("'")) return word.slice(1, -1).replace(/'\\''/g, "'");
+  if (word.startsWith('"')) return word.slice(1, -1);
+  return word;
+}
+
 const runsCarwash = (verb) => (command) => typeof command === 'string' && new RegExp(`carwash\\.mjs['"]?\\s+${verb}\\s*$`).test(command);
 export const isCarwashCommand = runsCarwash('statusline');
 export const isCarwashHook = runsCarwash('hook');
@@ -178,7 +188,10 @@ export function planInstall({ env = process.env, platform = process.platform } =
   };
   const skill = planSkill(env);
 
-  return { home, appDir, file, settings, record, original, alreadyInstalled, next, skill, keepsHooks: isPlainObject(theirHooks) && Object.keys(theirHooks).length > 0 };
+  // The Node the commands will run with. Windows finds `node` on PATH instead.
+  const node = platform === 'win32' ? null : script.nodePath;
+
+  return { home, appDir, file, settings, record, original, alreadyInstalled, next, skill, node, keepsHooks: isPlainObject(theirHooks) && Object.keys(theirHooks).length > 0 };
 }
 
 export function describeInstall(plan) {
@@ -202,6 +215,9 @@ export function describeInstall(plan) {
   }
   lines.push(`  3. Add the /wash command at ${tilde(plan.skill.dir)}`);
   lines.push('', 'Writing a brief is an ordinary Claude reply, so it uses tokens like any other.');
+  // Version managers such as nvm keep a folder per Node version, so removing
+  // an old version takes this path with it, and nothing of Carwash can start.
+  if (plan.node) lines.push(`Carwash runs with the Node at ${tilde(plan.node)}. If you remove that Node later, for example an old version in nvm, run install again.`);
   lines.push('Nothing else is touched. To undo everything: carwash uninstall');
   return lines.join('\n');
 }

package/src/install/update.mjs

@@ -1,9 +1,9 @@
 import { spawnSync } from 'node:child_process';
 
-// Whether a newer Context Carwash is on npm, and handing over to it. Only the
-// installer asks, since npx can quietly rerun a copy it downloaded earlier, and
-// people should not have to know to type @latest. The meter and /wash never
-// use the network.
+// Whether a newer Context Carwash is on npm, and handing over to it, for the
+// installer: npx can quietly rerun a copy it downloaded earlier, and people
+// should not have to know to type @latest. The daily check behind the update
+// notice is in notice.mjs. The meter and /wash never go online themselves.
 
 const LATEST_URL = 'https://registry.npmjs.org/context-carwash/latest';
 const TIMEOUT_MS = 3000;