context-carwash 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spobi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# Context Carwash
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, local-first utility for Claude Code.
+
+- **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 leaves your machine.
+
+**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.
+
+## Install
+
+Requires Node 18 or later.
+
+```sh
+npx context-carwash preview     # sample meters in your terminal, nothing installed
+npx context-carwash install     # lists what it will change, then asks
+```
+
+To update later, run `npx context-carwash@latest install` again. Waiting briefs are kept.
+
+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 meter
+
+```text
+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.
+
+A full meter is information. It never triggers anything.
+
+## Starting fresh with a brief
+
+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`.
+
+| Command | What it does |
+|---|---|
+| `/wash` | Write a `mid` brief |
+| `/wash light` | Goal, current state, next step |
+| `/wash mid` | Adds constraints, decisions, state detail, pitfalls |
+| `/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 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`.
+
+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.
+
+## Where things are kept
+
+Briefs are stored in `~/.carwash`, readable only by you, and never inside your project. Nothing is uploaded, and there is no telemetry.
+
+If a hook fails it stays silent and writes the error to `~/.carwash/errors.log`.
+
+## Uninstall
+
+```sh
+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.
+
+## 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.
+
+## License
+
+MIT

package/bin/carwash.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "context-carwash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A quiet context meter and deliberate fresh-session handoff for Claude Code.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Spobi/context-carwash.git"
+  },
+  "homepage": "https://github.com/Spobi/context-carwash#readme",
+  "bugs": "https://github.com/Spobi/context-carwash/issues",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "context",
+    "statusline"
+  ],
+  "type": "module",
+  "bin": {
+    "carwash": "bin/carwash.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,156 @@
+import { appendFileSync, existsSync, statSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { applyInstall, applyUninstall, describeInstall, describeUninstall, packageVersion, planInstall, planUninstall } from './install/install.mjs';
+import { UserError } from './install/settings.mjs';
+import { errorLogPath, welcomedPath } from './paths.mjs';
+import { render } from './statusline/render.mjs';
+import { statusline } from './statusline/run.mjs';
+import { runHook } from './wash/hooks.mjs';
+
+const HELP = `Context Carwash: a quiet context meter and a deliberate fresh start for Claude Code.
+
+Usage: carwash <command>
+
+  install [--yes]     Add the context meter and the /wash command to Claude Code
+  uninstall [--yes]   Undo everything install did
+  preview             Print sample meters in this terminal
+  --version           Print the version
+
+Inside Claude Code, once installed:
+
+  /wash [light | mid | detailed]   Write a handoff brief (mid if you do not say)
+  /clear                           Start fresh with the brief that is ready
+  /wash discard                    Drop the brief; /clear is a normal clear again
+  /wash load [id]                  Make a waiting brief the one /clear will use
+  /wash help                       Explain the meter and the options
+
+Nothing happens automatically, and nothing leaves this machine.`;
+
+async function readAll(stream) {
+  if (stream.isTTY) return '';
+  let text = '';
+  stream.setEncoding('utf8');
+  for await (const chunk of stream) text += chunk;
+  return text;
+}
+
+async function confirm(question, { yes, stdin, stdout }) {
+  if (yes) return true;
+  if (!stdin.isTTY) throw new UserError('Not running in a terminal, so there is nobody to ask. Re-run with --yes to confirm.');
+  const rl = createInterface({ input: stdin, output: stdout });
+  const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+function preview(env, stdout) {
+  const sample = (pct, size = 200_000) => ({
+    context_window: {
+      context_window_size: size,
+      used_percentage: pct,
+      current_usage: { input_tokens: 10, cache_creation_input_tokens: 0, cache_read_input_tokens: Math.round((pct / 100) * size) - 10 },
+    },
+  });
+  const columns = Math.max(20, (stdout.columns ?? 120) - 4);
+  const out = [];
+  for (const [style, label] of [['ramp', 'Each block keeps its own colour'], ['solid', 'Whole bar takes the colour of the current reading']]) {
+    out.push(`${label}:`);
+    for (const pct of [3, 25, 45, 60, 68, 75, 90, 99]) out.push(`  ${render(sample(pct), { env, columns: Infinity, barStyle: style }).text}`);
+    out.push('');
+  }
+  out.push('Narrower windows drop detail in this order:');
+  for (const width of [120, 100, 80, 60, 30, 10]) out.push(`  ${String(width).padStart(3)} cols  ${render(sample(68), { env, columns: width - 4 }).text}`);
+  out.push('', `This window (${columns + 4} columns), before any reply has arrived, then with 136k in use:`);
+  out.push(`  ${render({}, { env, columns }).text}`, `  ${render(sample(68), { env, columns }).text}`);
+  out.push('', 'While /wash is writing a brief, and once one is ready for /clear:');
+  out.push(`  ${render(sample(68), { env, columns, state: { washing: 'mid' } }).text}`);
+  out.push(`  ${render(sample(68), { env, columns, state: { ready: { level: 'mid', tokens: 3100 } } }).text}`);
+  stdout.write(out.join('\n') + '\n');
+}
+
+// A hook must never fail loudly inside someone's session, so its errors go to
+// a small private log instead of the screen.
+function logError(env, error) {
+  try {
+    const file = errorLogPath(env);
+    const line = `${new Date().toISOString()} ${error?.stack ?? error}\n`;
+    let size = 0;
+    try {
+      size = statSync(file).size;
+    } catch {
+      // no log yet
+    }
+    if (size > 200_000) writeFileSync(file, line, { mode: 0o600 });
+    else appendFileSync(file, line, { mode: 0o600 });
+  } catch {
+    // nowhere to write it
+  }
+}
+
+export async function main(argv, { env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const [command, ...rest] = argv;
+  const yes = rest.includes('--yes') || rest.includes('-y');
+  try {
+    switch (command) {
+      case 'statusline':
+        stdout.write((await statusline({ input: await readAll(stdin), env })) + '\n');
+        return 0;
+      case 'hook': {
+        let output = null;
+        try {
+          output = runHook({ input: await readAll(stdin), env });
+        } catch (error) {
+          logError(env, error);
+        }
+        if (output) stdout.write(JSON.stringify(output) + '\n');
+        return 0;
+      }
+      case 'install': {
+        const plan = planInstall({ env });
+        stdout.write(describeInstall(plan) + '\n\n');
+        if (!(await confirm('Proceed?', { yes, stdin, stdout }))) {
+          stdout.write('Nothing was changed.\n');
+          return 1;
+        }
+        applyInstall(plan);
+        const welcome = existsSync(welcomedPath(env)) ? '' : ' Its first message explains them.';
+        stdout.write(`Installed. Start a new Claude Code session to get the meter and /wash.${welcome}\n`);
+        return 0;
+      }
+      case 'uninstall': {
+        const plan = planUninstall({ env });
+        stdout.write(describeUninstall(plan) + '\n\n');
+        if (!(await confirm('Proceed?', { yes, stdin, stdout }))) {
+          stdout.write('Nothing was changed.\n');
+          return 1;
+        }
+        applyUninstall(plan);
+        stdout.write('Uninstalled.\n');
+        return 0;
+      }
+      case 'preview':
+        preview(env, stdout);
+        return 0;
+      case '--version':
+      case '-v':
+      case 'version':
+        stdout.write(packageVersion() + '\n');
+        return 0;
+      case undefined:
+      case 'help':
+      case '--help':
+      case '-h':
+        stdout.write(HELP + '\n');
+        return 0;
+      default:
+        stderr.write(`Unknown command: ${command}\n\n${HELP}\n`);
+        return 2;
+    }
+  } catch (error) {
+    if (error instanceof UserError) {
+      stderr.write(`carwash: ${error.message}\n`);
+      return 1;
+    }
+    throw error;
+  }
+}

package/src/files.mjs

@@ -0,0 +1,36 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const TEMP_SUFFIX = '.carwash-tmp';
+
+// A directory only this user can enter.
+export function privateDir(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  chmodSync(path, 0o700);
+  return path;
+}
+
+// Replace a file's contents in one step, keeping its permissions.
+export function writeFileAtomic(file, bytes, mode) {
+  mkdirSync(dirname(file), { recursive: true });
+  const keepMode = mode ?? (existsSync(file) ? statSync(file).mode & 0o777 : 0o600);
+  const temp = join(dirname(file), `.${process.pid}.${randomBytes(4).toString('hex')}${TEMP_SUFFIX}`);
+  writeFileSync(temp, bytes, { mode: keepMode });
+  renameSync(temp, file);
+}
+
+// Parsed contents of a JSON file, or null if it is missing or unreadable.
+export function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Write JSON into Carwash's own storage, readable by this user only.
+export function writePrivateJson(file, data) {
+  privateDir(dirname(file));
+  writeFileAtomic(file, JSON.stringify(data, null, 2) + '\n', 0o600);
+}