context-carwash 0.2.0 → 0.2.2

package/src/install/install.mjs

@@ -3,7 +3,8 @@ import { homedir } from 'node:os';
 import { delimiter, dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { privateDir, readJson, writeFileAtomic } from '../files.mjs';
-import { carwashHome, installRecordPath, legacyCommandPath, pendingDir, settingsPath, skillDir } from '../paths.mjs';
+import { carwashHome, claudeConfigDir, installRecordPath, legacyCommandPath, pendingDir, settingsPath, skillDir } from '../paths.mjs';
+import { applyCodexInstall, applyCodexUninstall, codexDetected, describeCodexInstall, describeCodexUninstall, planCodexInstall, planCodexUninstall } from './codex.mjs';
 import { UserError, readSettings, resolveSettingsFile, serializeSettings, sha256 } from './settings.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -85,8 +86,9 @@ export const isCarwashHook = runsCarwash('hook');
 
 // The `hooks` setting with Carwash's own entries taken out. An event's list,
 // or the whole setting, goes too if it only existed to hold ours. Returns the
-// same object when there was nothing of ours in it.
-export function withoutCarwashHooks(hooks) {
+// same object when there was nothing of ours in it. `isOurs` tells our hook
+// commands apart; Codex's hooks file has the same shape as Claude Code's.
+export function withoutCarwashHooks(hooks, isOurs = isCarwashHook) {
   if (!isPlainObject(hooks)) return hooks;
   const next = {};
   let found = false;
@@ -97,13 +99,13 @@ export function withoutCarwashHooks(hooks) {
     }
     const kept = [];
     for (const group of groups) {
-      const ours = Array.isArray(group?.hooks) && group.hooks.some((hook) => isCarwashHook(hook?.command));
+      const ours = Array.isArray(group?.hooks) && group.hooks.some((hook) => isOurs(hook?.command));
       if (!ours) {
         kept.push(group);
         continue;
       }
       found = true;
-      const theirs = group.hooks.filter((hook) => !isCarwashHook(hook?.command));
+      const theirs = group.hooks.filter((hook) => !isOurs(hook?.command));
       if (theirs.length) kept.push({ ...group, hooks: theirs });
     }
     if (kept.length || kept.length === groups.length) next[event] = kept;
@@ -155,13 +157,38 @@ function copyTree(from, to) {
   }
 }
 
+// Whether an install record covers Claude Code. Records from before Codex
+// support do not list their tools, and were all Claude Code.
+const claudeRecorded = (record) => Boolean(record) && (!Array.isArray(record.tools) || record.tools.includes('claude'));
+
+// Which tools an install covers. Codex when it is set up here. Claude Code when
+// it is set up here or was installed before, and always when Codex is not
+// there: that was the whole install before Codex support.
+export function detectTools(env = process.env, record = readJson(installRecordPath(env))) {
+  const codex = codexDetected(env);
+  const claude = existsSync(claudeConfigDir(env)) || claudeRecorded(record) || !codex;
+  return { claude, codex };
+}
+
 // Work out what installing would change, without changing anything.
 export function planInstall({ env = process.env, platform = process.platform } = {}) {
   const home = carwashHome(env);
   const appDir = join(home, 'app');
+  const record = readJson(installRecordPath(env));
+  const tools = detectTools(env, record);
+  const script = { nodePath: stableNodePath(env), scriptPath: join(appDir, 'bin', 'carwash.mjs'), platform };
+  // The Node the commands will run with. Windows finds `node` on PATH instead.
+  const node = platform === 'win32' ? null : script.nodePath;
+  const codex = tools.codex ? planCodexInstall({ env, script, previous: record?.codex ?? null }) : null;
+  if (!tools.claude) return { home, appDir, record, node, claude: false, codex };
+  return { ...planClaudeInstall({ env, record: claudeRecorded(record) ? record : null, script }), home, appDir, record, node, claude: true, codex };
+}
+
+// The Claude Code half of an install: the status line, hooks and /wash.
+// `record` is the install record when it covers Claude Code.
+function planClaudeInstall({ env, record, script }) {
   const file = resolveSettingsFile(settingsPath(env));
   const settings = readSettings(file);
-  const record = readJson(installRecordPath(env));
   const current = settings.data.statusLine;
 
   let original = null;
@@ -179,7 +206,6 @@ export function planInstall({ env = process.env, platform = process.platform } =
     }
   }
 
-  const script = { nodePath: stableNodePath(env), scriptPath: join(appDir, 'bin', 'carwash.mjs'), platform };
   const theirHooks = withoutCarwashHooks(settings.data.hooks);
   const next = {
     ...settings.data,
@@ -188,16 +214,30 @@ export function planInstall({ env = process.env, platform = process.platform } =
   };
   const skill = planSkill(env);
 
-  // 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 };
+  return { file, settings, claudeRecord: record, original, alreadyInstalled, next, skill, keepsHooks: isPlainObject(theirHooks) && Object.keys(theirHooks).length > 0 };
 }
 
 export function describeInstall(plan) {
   const lines = ['Context Carwash will make these changes:', ''];
   lines.push(`  1. Copy its files to ${tilde(plan.appDir)}`);
-  lines.push(`  2. ${plan.settings.exists ? 'Edit' : 'Create'} ${tilde(plan.file)}`);
+  if (plan.claude) lines.push(...describeClaudeInstall(plan));
+  if (plan.codex) lines.push(...describeCodexInstall(plan.codex, plan.claude ? 4 : 2, plan.home));
+  const model = plan.claude && plan.codex ? 'Claude or Codex' : plan.codex ? 'Codex' : 'Claude';
+  lines.push('', `Writing a brief is an ordinary ${model} 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');
+}
+
+// Steps 2 and 3: Claude Code. Labelled with its name only when Codex is in the
+// list too.
+function describeClaudeInstall(plan) {
+  const lines = [];
+  const label = plan.codex ? 'Claude Code: ' : '';
+  const verb = plan.settings.exists ? 'Edit' : 'Create';
+  lines.push(`  2. ${label}${label ? verb.toLowerCase() : verb} ${tilde(plan.file)}`);
   if (plan.alreadyInstalled) {
     lines.push('       The Carwash status line is already there; its command is refreshed.');
   } else if (plan.original) {
@@ -210,20 +250,15 @@ export function describeInstall(plan) {
   }
   lines.push('       Adds three hooks, so /wash can save a brief and a fresh session can');
   lines.push(`       pick it up.${plan.keepsHooks ? ' The hooks you already have are kept as they are.' : ''}`);
-  if (plan.settings.exists && !plan.record) {
+  if (plan.settings.exists && !plan.claudeRecord) {
     lines.push(`       A backup of the file is kept in ${tilde(join(plan.home, 'backup'))}`);
   }
-  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');
+  lines.push(`  3. ${label ? `${label}add` : 'Add'} the /wash command at ${tilde(plan.skill.dir)}`);
+  return lines;
 }
 
 export function applyInstall(plan) {
-  const { home, appDir, file, settings, record, skill } = plan;
+  const { home, appDir, record } = plan;
   privateDir(home);
 
   // Self-contained copy, so the status line keeps working if the package that
@@ -236,6 +271,20 @@ export function applyInstall(plan) {
     }
   }
 
+  const tools = [...(plan.claude ? ['claude'] : []), ...(plan.codex ? ['codex'] : [])];
+  const codex = plan.codex ? applyCodexInstall(plan.codex, home) : null;
+  const base = { version: packageVersion(), installedAt: record?.installedAt ?? new Date().toISOString() };
+  // Only the tools other than Claude Code are listed, so a Claude Code install
+  // records exactly what it did before Codex support.
+  const extra = { ...(tools.length === 1 && tools[0] === 'claude' ? {} : { tools }), ...(codex ? { codex } : {}) };
+  const nextRecord = plan.claude ? { ...base, ...applyClaudeInstall(plan), ...extra } : { ...base, ...extra };
+  writeFileSync(installRecordPath({ CARWASH_HOME: home }), JSON.stringify(nextRecord, null, 2) + '\n', { mode: 0o600 });
+  return nextRecord;
+}
+
+// Write the Claude Code half, and return what the install record keeps about it.
+function applyClaudeInstall(plan) {
+  const { home, file, settings, claudeRecord: record, skill } = plan;
   mkdirSync(skill.dir, { recursive: true });
   copyFileSync(SKILL_SOURCE, skill.file);
 
@@ -255,9 +304,7 @@ export function applyInstall(plan) {
   // promise is off for good and uninstall edits our own keys instead.
   const pristine = !record || (settings.exists && record.installedSha256 === sha256(settings.bytes));
 
-  const nextRecord = {
-    version: packageVersion(),
-    installedAt: record?.installedAt ?? new Date().toISOString(),
+  return {
     settingsPath: file,
     hadSettingsFile: record ? record.hadSettingsFile : settings.exists,
     backupPath,
@@ -266,8 +313,6 @@ export function applyInstall(plan) {
     statusLine: { original: plan.original },
     skillPath: skill.file,
   };
-  writeFileSync(installRecordPath({ CARWASH_HOME: home }), JSON.stringify(nextRecord, null, 2) + '\n', { mode: 0o600 });
-  return nextRecord;
 }
 
 function countBriefs(env) {
@@ -281,9 +326,13 @@ function countBriefs(env) {
 // Work out what uninstalling would change, without changing anything.
 export function planUninstall({ env = process.env } = {}) {
   const home = carwashHome(env);
-  const record = readJson(installRecordPath(env));
+  const installRecord = readJson(installRecordPath(env));
+  // What install noted about Claude Code. An install for Codex alone has
+  // nothing to say about it, so Claude Code's settings are only checked for
+  // Carwash entries, as without a record.
+  const record = claudeRecorded(installRecord) ? installRecord : null;
   const file = resolveSettingsFile(record?.settingsPath ?? settingsPath(env));
-  const plan = { home, file, record, action: 'none', note: null, bytes: null };
+  const plan = { home, file, record: installRecord, action: 'none', note: null, bytes: null };
 
   if (existsSync(file)) {
     const current = readFileSync(file);
@@ -325,6 +374,12 @@ export function planUninstall({ env = process.env } = {}) {
   plan.skillDir = dirname(skillFile);
   plan.skill = isOurSkill(skillFile) ? skillFile : null;
   plan.foreignSkill = !plan.skill && existsSync(skillFile);
+  // Claude Code is in the list unless install never touched it and there is
+  // nothing of Carwash's there now.
+  plan.claude = Boolean(record) || !installRecord || plan.action !== 'none' || Boolean(plan.skill);
+
+  plan.codex = planCodexUninstall({ env, record: installRecord?.codex ?? null });
+  if (!plan.codex.found && !installRecord?.codex) plan.codex = null;
 
   // Only ever delete a directory that is recognisably ours, and never the
   // home directory or a filesystem root, whatever CARWASH_HOME says.
@@ -343,9 +398,13 @@ export function describeUninstall(plan) {
     edit: `Edit ${tilde(plan.file)}: undo Carwash's status line and hooks; your other changes stay`,
     none: `Leave ${tilde(plan.file)} alone`,
   }[plan.action];
-  const steps = [[what, plan.note]];
-  if (plan.skill) steps.push([`Remove the /wash command at ${tilde(plan.skillDir)}`]);
-  else if (plan.foreignSkill) steps.push([`Leave the /wash command at ${tilde(plan.skillDir)} alone (not Carwash's)`]);
+  const steps = [];
+  if (plan.claude) {
+    steps.push([what, plan.note]);
+    if (plan.skill) steps.push([`Remove the /wash command at ${tilde(plan.skillDir)}`]);
+    else if (plan.foreignSkill) steps.push([`Leave the /wash command at ${tilde(plan.skillDir)} alone (not Carwash's)`]);
+  }
+  if (plan.codex) steps.push(...describeCodexUninstall(plan.codex));
   const briefs = plan.briefs ? `, including ${plan.briefs} waiting ${plan.briefs === 1 ? 'brief' : 'briefs'}` : '';
   steps.push([plan.removeHome ? `Delete ${tilde(plan.home)}${briefs}` : `Leave ${tilde(plan.home)} alone (not a Carwash folder)`]);
   steps.forEach(([step, note], i) => {
@@ -366,5 +425,6 @@ export function applyUninstall(plan) {
       // the folder holds something else, which stays
     }
   }
+  if (plan.codex) applyCodexUninstall(plan.codex);
   if (plan.removeHome) rmSync(plan.home, { recursive: true, force: true });
 }

package/src/paths.mjs

@@ -11,6 +11,11 @@ export function claudeConfigDir(env = process.env) {
   return env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
 }
 
+// Codex's own home directory, honouring its documented override.
+export function codexHome(env = process.env) {
+  return env.CODEX_HOME || join(homedir(), '.codex');
+}
+
 export function settingsPath(env = process.env) {
   return join(claudeConfigDir(env), 'settings.json');
 }
@@ -43,9 +48,19 @@ export const errorsSeenPath = (env = process.env) => join(carwashHome(env), 'err
 // the author put on this one.
 export const noticePath = (env = process.env) => join(carwashHome(env), 'notice.json');
 
-// Present once the first-run welcome has been shown.
-export const welcomedPath = (env = process.env) => join(carwashHome(env), 'welcomed');
+// Present once the first-run welcome has been shown. Each tool says hello once.
+export const welcomedPath = (env = process.env, tool = 'claude') => join(carwashHome(env), tool === 'claude' ? 'welcomed' : `welcomed-${tool}`);
 
 // Where the /wash command is installed.
 export const skillDir = (env = process.env) => join(claudeConfigDir(env), 'skills', 'wash');
 export const legacyCommandPath = (env = process.env) => join(claudeConfigDir(env), 'commands', 'wash.md');
+
+// Where Carwash goes in Codex: its hooks file, the $wash skill, and the config
+// file Codex keeps hook approvals in (read, never written).
+export const codexHooksPath = (env = process.env) => join(codexHome(env), 'hooks.json');
+export const codexSkillDir = (env = process.env) => join(codexHome(env), 'skills', 'wash');
+export const codexConfigPath = (env = process.env) => join(codexHome(env), 'config.toml');
+
+// What Carwash has learned about how far sessions usually go: a few numbers
+// per transcript, so the transcripts need not be read again.
+export const habitsPath = (env = process.env) => join(carwashHome(env), 'habits.json');

package/src/skill/codex/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: wash
+description: Context Carwash. Writes a short handoff brief of this session when the user types $wash, so that /clear can start a fresh session that carries on from it. Use only when the user's message starts with $wash.
+metadata:
+  installed-by: context-carwash
+---
+
+The user typed $wash. Context Carwash saves your reply as a handoff brief, but only while its hooks are running. When they are, they add a developer message to this turn that starts with "Carwash: level".
+
+**First, look for that message.** If this turn has no developer message starting with "Carwash: level", the hooks are not running and a brief would be lost. Then do not write a brief. Reply with only this: "Carwash's hooks aren't running in Codex yet, so no brief was saved. Restart Codex and choose "Trust all and continue" when it asks about hooks, then run $wash again. If that doesn't help, run `npx context-carwash doctor` in a terminal."
+
+When the message is there: the user wants to start a fresh session that picks up where this one leaves off. Your whole reply to this message is saved as the handoff brief, and it is the first thing the next session reads. That session cannot see this conversation, so anything the brief leaves out is gone.
+
+The words after $wash in the user's message are the arguments. The first word is the level: `light`, `mid`, or `detailed`. No arguments means `mid`. Anything after the level is the user's note on what to emphasise.
+
+Reply with the brief and nothing else: no preamble, no closing remark, no code fence around it. Do not call tools or read files to prepare. Write from what is already in this conversation.
+
+## Format
+
+Start with exactly this heading, then the Core section:
+
+```
+# Carwash brief: <the task, in under 60 characters>
+
+## Core
+- Objective: what the user is trying to get done, and how they will know it is done
+- State: where things stand right now
+- Next: the one concrete action to take first
+```
+
+Core must stand on its own in under 1,000 characters. A session that reads only Core should still start in the right place.
+
+After Core, add only the sections for the level, and skip any that would be empty:
+
+- `light`: Core only. Add one line for a critical constraint if breaking it would undo the work.
+- `mid`: **Constraints** (the user's corrections and preferences that still apply), **Decisions** (what was settled, with the reason in a clause), **State** (files and branches changed, commands and tests run with their results, uncommitted work, blockers), **Pitfalls** (what to avoid, and approaches that failed).
+- `detailed`: everything in `mid`, plus **Rationale** for the main decisions, **History** (experiments worth knowing about and what each one showed), **Test results**, **Risks and open assumptions**, and **Steps** (a checklist of what remains).
+
+## Rules
+
+- Write the smallest brief that lets a fresh session continue, and stop when it is complete. The token ceiling given with this command is a limit, not a target. Most briefs should end well under it. Never pad.
+- This is a brief for continuing a task, not a summary of the conversation. Leave out greetings, repetition, plans that were replaced, and raw tool output.
+- Leave out what the next session is given anyway: your standing instructions, project memory and AGENTS.md contents, tool descriptions, and the environment or git status shown at the start of this session.
+- Point to files, diffs, and tests by path, with a line number or function name where that helps. Do not copy their contents.
+- Keep confirmed facts apart from assumptions, and label the assumptions.
+- Never invent a test result, and never say a file was inspected unless it was read in this conversation.
+- Never copy credentials, tokens, keys, or other secrets.

package/src/skill/codex/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Context Carwash: $wash runs only when typed, never because a prompt seems to fit.
+policy:
+  allow_implicit_invocation: false

package/src/stats/habits.mjs

@@ -0,0 +1,107 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJson, writePrivateJson } from '../files.mjs';
+import { claudeConfigDir, habitsPath } from '../paths.mjs';
+import { DEFAULT_SHARE, isPrompt, sentOf } from './ledger.mjs';
+
+// How far this person usually takes a session, learned from their own Claude
+// Code transcripts. A wash saves context only for the prompts that would
+// otherwise have been sent in the old session, and that depends on habit:
+// someone who often clears at 300k would not have gone on for long past it.
+// Everything here stays on this machine; the cache holds only sizes.
+
+const PRIOR_WEIGHT = 10; // the starting guess counts as this many sessions
+const SETTLE_MS = 3_600_000; // touched this recently, a session may still be going
+const FIRST_READ_MS = 90 * 24 * 3_600_000; // older transcripts are not read for the first time
+
+const WASH = /<command-name>\/wash<\/command-name>(?:\\n)?<command-args>(?:light|mid|detailed)?<\/command-args>/;
+
+// A session's shape: its size when each prompt was answered, whether it
+// compacted (so went on to the limit), and whether it ended in a wash.
+export function sessionShape(text) {
+  const sizes = [];
+  let waiting = false;
+  let compacted = false;
+  for (const raw of text.split('\n')) {
+    if (!raw.includes('"user"') && !raw.includes('"usage"') && !raw.includes('compact_boundary')) continue;
+    let line;
+    try {
+      line = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!line || line.isSidechain) continue;
+    if (line.type === 'system' && line.subtype === 'compact_boundary') {
+      compacted = true;
+      break;
+    }
+    if (isPrompt(line)) waiting = true;
+    else if (waiting && line.type === 'assistant' && line.message?.usage) {
+      sizes.push(sentOf(line.message.usage));
+      waiting = false;
+    }
+  }
+  return { sizes, compacted, washed: WASH.test(text) };
+}
+
+// Bring the cache up to date with Claude Code's transcripts and return every
+// session's shape. Transcripts Claude Code has since deleted stay in the cache.
+export function learnHabits(env, { now = Date.now() } = {}) {
+  const file = habitsPath(env);
+  const sessions = readJson(file)?.sessions ?? {};
+  const root = join(claudeConfigDir(env), 'projects');
+  let changed = false;
+  let dirs = [];
+  try {
+    dirs = readdirSync(root);
+  } catch {
+    // no transcripts
+  }
+  for (const dir of dirs) {
+    let names;
+    try {
+      names = readdirSync(join(root, dir));
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (!name.endsWith('.jsonl')) continue;
+      const path = join(root, dir, name);
+      try {
+        const { mtimeMs } = statSync(path);
+        if (now - mtimeMs < SETTLE_MS || sessions[path]?.mtime === mtimeMs) continue;
+        if (!sessions[path] && now - mtimeMs > FIRST_READ_MS) continue;
+        sessions[path] = { mtime: mtimeMs, ...sessionShape(readFileSync(path, 'utf8')) };
+        changed = true;
+      } catch {
+        continue;
+      }
+    }
+  }
+  if (changed) {
+    try {
+      writePrivateJson(file, { version: 1, sessions });
+    } catch {
+      // learned again next time
+    }
+  }
+  return Object.values(sessions).filter((s) => !s.washed && Array.isArray(s.sizes) && s.sizes.length);
+}
+
+// The share of `turns` prompts, sent after washing a session of `before`
+// tokens, that would likely have been sent in that session anyway. Each past
+// session that reached the same size says how many more prompts it went on
+// for; one that compacted went on to the limit. The starting guess holds until
+// enough sessions have reached that size to outweigh it.
+export function shareFor(sessions, before, turns) {
+  if (!(turns > 0) || !(before > 0)) return DEFAULT_SHARE;
+  let seen = 0;
+  let kept = 0;
+  for (const { sizes, compacted } of sessions) {
+    const at = sizes.findIndex((size) => size >= before);
+    if (at < 0) continue;
+    seen++;
+    kept += compacted ? 1 : Math.min(turns, sizes.length - 1 - at) / turns;
+  }
+  return (DEFAULT_SHARE * PRIOR_WEIGHT + kept) / (PRIOR_WEIGHT + seen);
+}