context-carwash 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.2
+
+- `carwash stats` leads with a likelier saving and shows the old figure as the most it could be. It counts only the first part of the prompts after each wash, since you would have cleared the old conversation at some point anyway. That share starts at two-thirds and is learned from how far your own Claude Code conversations go, read on your machine. Output the fresh conversation had to read again, which the old one already had, is taken off.
+- `stats --share` sends the likely figure as well as the full one.
+
+## 0.2.1
+
+- Codex support. `install` sets up Codex too when it finds it: three hooks in `~/.codex/hooks.json` and a `$wash` command in `~/.codex/skills/wash`. Codex asks you to trust the hooks once. After `/clear`, the brief loads with your next message. Codex's status line can only show its own items, so the meter is a line after each reply instead, in colour from Codex 0.162.0 on. It is shown to you only and costs no tokens.
+- `carwash doctor` checks the Codex hooks, whether Codex trusts them, and `$wash`.
+- `carwash stats` counts Codex sessions too.
+- Claude Code works exactly as before. A brief from one tool is not picked up by the other unless you load it by id.
+
 ## 0.2.0
 
 - README demo GIF and a one-line summary at the top.

package/README.md

@@ -1,6 +1,6 @@
 # Context Carwash
 
-*Long Claude Code sessions get slow and forgetful. Run it through the wash: keep what matters, drop the rest, start fresh.*
+*Long Claude Code and Codex sessions get slow and forgetful. Run it through the wash: keep what matters, drop the rest, start fresh.*
 
 ![The meter fills up, /wash writes a short brief, and after /clear a fresh session picks up where the old one stopped](docs/demo.gif)
 
@@ -9,6 +9,8 @@ Context Carwash adds a line to Claude Code in your terminal that:
 1. **The Meter:** shows the current conversation's context size.
 2. **/wash:** lets you compress your context and start a new session without losing important details.
 
+It works in Codex too: see [Codex](#codex).
+
 Pretty simple app, but I've found it helpful. Everything is local, but you can share your token savings anonymously with me if you'd like with `npx context-carwash stats --share`.
 
 ## Install
@@ -19,11 +21,11 @@ You'll need Node 18 or later.
 npx context-carwash install
 ```
 
-It shows you what it's going to change and asks before doing anything. Then start a new Claude Code session and you're set.
+It shows you what it's going to change and asks before doing anything. Then start a new Claude Code session and you're set. If you use Codex as well, it sets that up in the same go.
 
 When there's a new version, a line under the meter will tell you. To update, run `npx context-carwash@latest install`.
 
-Under the hood, it adds a status line and three hooks to `~/.claude/settings.json` (after whatever you already have there) and a `/wash` command in `~/.claude/skills/wash`.
+Under the hood, it adds a status line and three hooks to `~/.claude/settings.json` (after whatever you already have there) and a `/wash` command in `~/.claude/skills/wash`. For Codex, it adds three hooks to `~/.codex/hooks.json` and a `$wash` command in `~/.codex/skills/wash`.
 
 ## The Meter
 
@@ -60,6 +62,19 @@ A few things worth knowing:
 - Closed the terminal before you got to `/clear`? Run `claude` in the same folder and your brief loads. If there's more than one waiting, it'll list them so you can pick with `/wash load <id>`.
 - Briefs expire after 48 hours.
 
+## Codex
+
+If you have Codex, `install` sets it up too. It works the same way, with a few differences:
+
+- The command is `$wash` (Codex keeps `/` for its own commands). Same options: `$wash light`, `$wash discard`, `$wash help` and so on.
+- Codex asks you to approve new hooks before it runs them. The first time you start Codex after installing, choose **Trust all and continue**.
+- After `/clear`, send your next message (even just "continue"). The brief loads with it, because that's when Codex starts the new session.
+- The meter shows up as a line after each reply, because Codex's status line can only show its own items:
+  `session context ~70k  [████░░░░░░░░░░░]  $wash to compress, then /clear`
+  The bar is in colour from Codex 0.162.0 on (plain text before that, or with `NO_COLOR`). It's shown to you only, never sent to the model, so it costs no tokens.
+- A brief written in Claude Code isn't picked up by Codex on its own, and the other way round. To use one anyway, run `$wash load <id>` (or `/wash load <id>`).
+- `codex exec` runs never use up a brief.
+
 ## Stats
 
 ```sh
@@ -72,12 +87,16 @@ Carwash stats, since 3 Oct 2026 (12 days)
   Briefs written              7  (light 1 · mid 5 · detailed 1)
   Started fresh with one      6
   Prompts in fresh sessions   94  (410 requests to Claude)
-  Context not re-sent         ~21M tokens
+  Context not re-sent         ~11M tokens  (at most ~21M tokens)
   Spent writing briefs        ~0.9M tokens
-  Net saved                   ~20M tokens
+  Net saved                   ~10M tokens  (at most ~20M tokens)
 ```
 
-Every request to Claude sends the whole conversation again. 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 of the price for repeated context, so in dollars you're saving roughly a tenth of these numbers. You can also see this inside Claude Code with `/wash stats`.
+Every request to Claude or Codex sends the whole conversation again. After a wash, each request starts from the small brief instead, so Carwash counts the requests you actually made and adds up the difference. Counting stops where the old conversation would have filled up and compacted on its own.
+
+You wouldn't have kept going in the old conversation forever, so the main number only counts the first part of the prompts after each wash. That's two-thirds to begin with. Carwash then adjusts it by looking at how far your own past conversations went once they were that big, so if you usually clear around 300k, a wash at 300k counts for less. Anything the fresh conversation had to read again, like a file the old one already had open, is taken off too. "At most" counts every prompt. All of this is worked out on your computer from Claude Code's own history files, and only a few numbers per conversation are kept.
+
+Repeated context is charged at about a tenth of the price, so in dollars you're saving roughly a tenth of these numbers. You can also see this inside Claude Code with `/wash stats`.
 
 If you run `stats --share`, it shows you exactly what it would send before asking.
 
@@ -99,11 +118,11 @@ Your briefs, stats and error logs live in `~/.carwash`, and only you can read th
 npx context-carwash uninstall
 ```
 
-This puts `settings.json` back exactly as it was. If you've edited the file since installing, it only removes Carwash's status line and hooks and leaves your changes alone. It also removes the `/wash` command and deletes `~/.carwash`, including any waiting briefs and your stats.
+This puts `settings.json` back exactly as it was. If you've edited the file since installing, it only removes Carwash's status line and hooks and leaves your changes alone. Codex's `hooks.json` gets the same treatment. It also removes the `/wash` and `$wash` commands and deletes `~/.carwash`, including any waiting briefs and your stats.
 
 ## Platforms
 
-Built and tested on macOS. Automated tests also run on Linux and Windows, but I haven't tried those by hand yet.
+Built and tested on macOS, with Claude Code and with Codex. Automated tests also run on Linux and Windows, but I haven't tried those by hand yet.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "context-carwash",
-  "version": "0.2.0",
-  "description": "A quiet context meter and deliberate fresh-session handoff for Claude Code.",
+  "version": "0.2.2",
+  "description": "A quiet context meter and deliberate fresh-session handoff for Claude Code and Codex.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -12,6 +12,7 @@
   "keywords": [
     "claude",
     "claude-code",
+    "codex",
     "context",
     "statusline"
   ],

package/src/cli.mjs

@@ -1,23 +1,22 @@
 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 { claudeVersion, doctorReport, markErrorsSeen } from './install/doctor.mjs';
+import { claudeVersion, codexInScope, codexVersion, doctorReport, markErrorsSeen } from './install/doctor.mjs';
 import { fetchNotice, refreshNotice, startCheck } from './install/notice.mjs';
 import { UserError } from './install/settings.mjs';
 import { isNewer, latestVersion, runRelease } from './install/update.mjs';
 import { errorLogPath, installRecordPath, welcomedPath } from './paths.mjs';
 import { readJson } from './files.mjs';
-import { refreshLedger, totals } from './stats/ledger.mjs';
-import { FORM, describeShare, sendShare, shareId, sharePayload, shareReady, statsReport } from './stats/report.mjs';
+import { FORM, describeShare, sendShare, shareId, sharePayload, shareReady, statsReport, currentTotals } from './stats/report.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.
+const HELP = `Context Carwash: a quiet context meter and a deliberate fresh start for Claude Code and Codex.
 
 Usage: carwash <command>
 
-  install [--yes]     Add the context meter and the /wash command to Claude Code
+  install [--yes]     Add the context meter and /wash to Claude Code, and $wash to Codex if you have it
   uninstall [--yes]   Undo everything install did
   preview             Print sample meters in this terminal
   stats [--share]     Show how much context /wash has saved; --share sends the totals anonymously, after asking
@@ -33,6 +32,9 @@ Inside Claude Code, once installed:
   /wash stats                      The same totals as carwash stats
   /wash help                       Explain the meter and the options
 
+In Codex it is $wash, with the same options. After /clear, the brief loads
+with the first message you send. Codex shows the meter after each reply.
+
 Nothing happens automatically, and nothing about you is ever sent. Once a day a
 new session reads Carwash's public page on npm for the newest version and any
 warning about yours (CARWASH_NO_UPDATE_CHECK=1 turns that off). install and
@@ -99,7 +101,16 @@ function logError(env, error) {
   }
 }
 
-export async function main(argv, { env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, latest = latestVersion, handOff = runRelease, form = FORM, share = sendShare, notice = fetchNotice, claude = claudeVersion, check = startCheck } = {}) {
+// What to do next, after an install, for each tool it covered.
+function installedMessage(plan, env) {
+  const welcome = existsSync(welcomedPath(env, 'claude')) ? '' : ' Its first message explains them.';
+  const codex = 'choose "Trust all and continue" when it asks about new hooks. Then type $wash when you want a fresh start.';
+  if (!plan.codex) return `Installed. Start a new Claude Code session to get the meter and /wash.${welcome}`;
+  if (!plan.claude) return `Installed. Start Codex and ${codex}`;
+  return ['Installed.', `  Claude Code: start a new session to get the meter and /wash.${welcome}`, `  Codex: start a new session and ${codex}`].join('\n');
+}
+
+export async function main(argv, { env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, latest = latestVersion, handOff = runRelease, form = FORM, share = sendShare, notice = fetchNotice, claude = claudeVersion, codex = codexVersion, check = startCheck } = {}) {
   const [command, ...rest] = argv;
   const yes = rest.includes('--yes') || rest.includes('-y');
   try {
@@ -111,7 +122,8 @@ export async function main(argv, { env = process.env, stdin = process.stdin, std
         let output = null;
         try {
           const version = packageVersion();
-          output = runHook({ input: await readAll(stdin), env, version, onError: (error) => logError(env, error), checkUpdates: () => check(version, { env }) });
+          // `carwash hook` is Claude Code's; Codex's hooks run `carwash hook codex`.
+          output = runHook({ input: await readAll(stdin), tool: rest[0] ?? 'claude', env, version, onError: (error) => logError(env, error), checkUpdates: () => check(version, { env }) });
         } catch (error) {
           logError(env, error);
         }
@@ -141,8 +153,7 @@ export async function main(argv, { env = process.env, stdin = process.stdin, std
         applyInstall(plan);
         // Errors from before this install are not news.
         markErrorsSeen(env);
-        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`);
+        stdout.write(`${installedMessage(plan, env)}\n`);
         return 0;
       }
       case 'uninstall': {
@@ -157,7 +168,7 @@ export async function main(argv, { env = process.env, stdin = process.stdin, std
         return 0;
       }
       case 'stats': {
-        const sum = totals(refreshLedger(env, { force: true }));
+        const sum = currentTotals(env);
         stdout.write(statsReport(sum) + '\n');
         if (!rest.includes('--share')) return 0;
         stdout.write('\n');
@@ -189,7 +200,7 @@ export async function main(argv, { env = process.env, stdin = process.stdin, std
         const running = packageVersion();
         const installed = readJson(installRecordPath(env))?.version;
         const newest = await notice(typeof installed === 'string' ? installed : running, { env });
-        stdout.write(doctorReport({ env, running, newest, claude: claude({ env }) }) + '\n');
+        stdout.write(doctorReport({ env, running, newest, claude: claude({ env }), codex: codexInScope(env) ? codex({ env }) : null }) + '\n');
         markErrorsSeen(env);
         return 0;
       }

package/src/install/codex.mjs

@@ -0,0 +1,256 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { privateDir, writeFileAtomic } from '../files.mjs';
+import { codexConfigPath, codexHome, codexHooksPath, codexSkillDir } from '../paths.mjs';
+import { UserError, readSettings, resolveSettingsFile, serializeSettings, sha256 } from './settings.mjs';
+import { commandFor, withoutCarwashHooks } from './install.mjs';
+
+// Carwash in Codex: three hooks in Codex's hooks file (~/.codex/hooks.json)
+// and the $wash skill in ~/.codex/skills/wash. Codex's own config.toml is
+// never written. Codex asks the person to trust new hooks before it runs them,
+// and keeps that answer in config.toml; Carwash only reads it, for doctor.
+//
+// The hooks file has the same shape as Claude Code's `hooks` setting, so it is
+// added to and taken out of the same way, and put back byte-for-byte when it
+// has not changed since install.
+
+const SKILL_SOURCE = fileURLToPath(new URL('../skill/codex', import.meta.url));
+const SKILL_FILES = ['SKILL.md', join('agents', 'openai.yaml')];
+const SKILL_MARK = 'installed-by: context-carwash';
+
+// What each hook is narrowed to. Codex ignores matchers on UserPromptSubmit
+// and Stop, so those run for every prompt and every reply, and return at once
+// when there is no $wash. SessionStart passes the brief through whole: by
+// default Codex saves context over 2,500 tokens to a file and shows the model
+// only the start and end. The status message is the name Codex shows when it
+// asks the person to trust the hooks, and beside one that runs slowly.
+export const CODEX_HOOKS = {
+  SessionStart: { group: { matcher: 'startup|clear' }, handler: { additionalContextLimit: 0 } },
+  UserPromptSubmit: { group: {}, handler: {} },
+  Stop: { group: {}, handler: {} },
+};
+const HOOK_TIMEOUT_SECONDS = 20;
+const HOOK_NAME = 'Context Carwash';
+
+export const isCarwashCodexHook = (command) => typeof command === 'string' && /carwash\.mjs['"]?\s+hook\s+codex\s*$/.test(command);
+
+const tilde = (path) => (path.startsWith(homedir() + sep) ? `~${path.slice(homedir().length)}` : path);
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// Whether Codex is set up on this machine: it makes its home folder the first
+// time it runs.
+export const codexDetected = (env = process.env) => existsSync(codexHome(env));
+
+function withCarwashCodexHooks(hooks, command, file) {
+  const refuse = () => {
+    throw new UserError(`${tilde(file)} has a "hooks" setting that Carwash does not know how to add to. Nothing was changed.`);
+  };
+  if (hooks !== undefined && !isPlainObject(hooks)) refuse();
+  const next = { ...(withoutCarwashHooks(hooks, isCarwashCodexHook) ?? {}) };
+  for (const [event, { group, handler }] of Object.entries(CODEX_HOOKS)) {
+    if (next[event] !== undefined && !Array.isArray(next[event])) refuse();
+    next[event] = [...(next[event] ?? []), { ...group, hooks: [{ type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS, statusMessage: HOOK_NAME, ...handler }] }];
+  }
+  return next;
+}
+
+function isOurSkill(file) {
+  try {
+    return readFileSync(file, 'utf8').includes(SKILL_MARK);
+  } catch {
+    return false;
+  }
+}
+
+// Hooks written straight into config.toml, which Codex also reads. Approvals
+// live under [hooks.state] and do not count.
+function inlineHooks(env) {
+  try {
+    return /^\s*\[\[?\s*hooks\.(?!state\b)/m.test(readFileSync(codexConfigPath(env), 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+// Work out what installing in Codex would change, without changing anything.
+// `script` is where the installed copy of Carwash will be; `previous` is what
+// an earlier install recorded about Codex, if anything.
+export function planCodexInstall({ env = process.env, script, previous = null }) {
+  const file = resolveSettingsFile(codexHooksPath(env));
+  const settings = readSettings(file);
+  const next = { ...settings.data, hooks: withCarwashCodexHooks(settings.data.hooks, commandFor('hook codex', script), file) };
+  const dir = codexSkillDir(env);
+  const skillFile = join(dir, 'SKILL.md');
+  if (existsSync(skillFile) && !isOurSkill(skillFile)) {
+    throw new UserError(`You already have a Codex skill called wash at ${tilde(dir)}, and Carwash needs that name. Nothing was changed. Rename or remove yours, then run install again.`);
+  }
+  const theirHooks = withoutCarwashHooks(settings.data.hooks, isCarwashCodexHook);
+  return {
+    file,
+    settings,
+    next,
+    previous,
+    skill: { dir, file: skillFile },
+    keepsHooks: isPlainObject(theirHooks) && Object.keys(theirHooks).length > 0,
+    inlineHooks: inlineHooks(env),
+  };
+}
+
+// The install steps for Codex, numbered from `first`. `home` is Carwash's own
+// folder, where a backup goes.
+export function describeCodexInstall(plan, first, home) {
+  const lines = [];
+  lines.push(`  ${first}. Codex: ${plan.settings.exists ? 'edit' : 'create'} ${tilde(plan.file)}`);
+  lines.push('       Adds three hooks, so $wash can save a brief and a fresh session can pick it up.');
+  if (plan.keepsHooks) lines.push('       The hooks you already have there are kept as they are.');
+  lines.push('       Codex asks you to trust new hooks before it runs them: the next time it');
+  lines.push('       starts, choose "Trust all and continue".');
+  if (plan.inlineHooks) lines.push('       You also have hooks in config.toml, so Codex will note hooks in two places. Both keep working.');
+  if (plan.settings.exists && !plan.previous) lines.push(`       A backup of the file is kept in ${tilde(join(home, 'backup'))}`);
+  lines.push(`  ${first + 1}. Codex: add the $wash command at ${tilde(plan.skill.dir)}`);
+  return lines;
+}
+
+export function applyCodexInstall(plan, home) {
+  const { file, settings, previous, skill } = plan;
+  for (const name of SKILL_FILES) {
+    mkdirSync(dirname(join(skill.dir, name)), { recursive: true });
+    copyFileSync(join(SKILL_SOURCE, name), join(skill.dir, name));
+  }
+
+  // The first install records what was there; later runs must not overwrite it.
+  let backupPath = previous?.backupPath ?? null;
+  if (!previous && settings.exists) {
+    privateDir(join(home, 'backup'));
+    backupPath = join(home, 'backup', 'codex-hooks.json');
+    writeFileSync(backupPath, settings.bytes, { mode: 0o600 });
+  }
+
+  const bytes = serializeSettings(plan.next, settings);
+  writeFileAtomic(file, bytes, settings.exists ? undefined : 0o600);
+  const pristine = !previous || (settings.exists && previous.installedSha256 === sha256(settings.bytes));
+  return {
+    hooksPath: file,
+    hadHooksFile: previous ? previous.hadHooksFile : settings.exists,
+    backupPath,
+    originalSha256: previous ? previous.originalSha256 : settings.exists ? sha256(settings.bytes) : null,
+    installedSha256: pristine ? sha256(bytes) : null,
+    skillDir: skill.dir,
+  };
+}
+
+// Work out what uninstalling from Codex would change. `record` is what install
+// noted about Codex, or null (no record, or an install from before Codex
+// support): then only Carwash's own entries are looked for and taken out.
+export function planCodexUninstall({ env = process.env, record = null }) {
+  const file = resolveSettingsFile(record?.hooksPath ?? codexHooksPath(env));
+  const plan = { file, action: 'none', bytes: null };
+  if (existsSync(file)) {
+    const current = readFileSync(file);
+    const backupOk = record?.backupPath && existsSync(record.backupPath) && sha256(readFileSync(record.backupPath)) === record.originalSha256;
+    if (record && sha256(current) === record.installedSha256 && !record.hadHooksFile) {
+      plan.action = 'delete';
+    } else if (record && sha256(current) === record.installedSha256 && backupOk) {
+      plan.action = 'restore';
+      plan.bytes = readFileSync(record.backupPath);
+    } else {
+      // The file changed after install: undo only our own entries and keep the rest.
+      const settings = readSettings(file);
+      const hooks = withoutCarwashHooks(settings.data.hooks, isCarwashCodexHook);
+      if (hooks !== settings.data.hooks) {
+        const data = { ...settings.data };
+        if (hooks === undefined) delete data.hooks;
+        else data.hooks = hooks;
+        if (!Object.keys(data).length && record && !record.hadHooksFile) {
+          plan.action = 'delete';
+        } else {
+          plan.action = 'edit';
+          plan.bytes = serializeSettings(data, settings);
+        }
+      }
+    }
+  }
+  const dir = record?.skillDir ?? codexSkillDir(env);
+  plan.skillDir = dir;
+  plan.skill = isOurSkill(join(dir, 'SKILL.md'));
+  plan.foreignSkill = !plan.skill && existsSync(join(dir, 'SKILL.md'));
+  plan.found = plan.action !== 'none' || plan.skill;
+  return plan;
+}
+
+export function describeCodexUninstall(plan) {
+  const steps = [];
+  const what = {
+    restore: `Codex: restore ${tilde(plan.file)} to exactly what it was before install`,
+    delete: `Codex: delete ${tilde(plan.file)} (Carwash created it and it has not changed since)`,
+    edit: `Codex: edit ${tilde(plan.file)}: take out Carwash's hooks; everything else stays`,
+  }[plan.action];
+  if (what) steps.push([what]);
+  if (plan.skill) steps.push([`Codex: remove the $wash command at ${tilde(plan.skillDir)}`]);
+  else if (plan.foreignSkill && plan.action !== 'none') steps.push([`Codex: leave the wash skill at ${tilde(plan.skillDir)} alone (not Carwash's)`]);
+  return steps;
+}
+
+export function applyCodexUninstall(plan) {
+  if (plan.action === 'restore' || plan.action === 'edit') writeFileAtomic(plan.file, plan.bytes);
+  if (plan.action === 'delete') unlinkSync(plan.file);
+  if (plan.skill) {
+    for (const name of SKILL_FILES) {
+      try {
+        unlinkSync(join(plan.skillDir, name));
+      } catch {
+        // already gone
+      }
+    }
+    for (const dir of [join(plan.skillDir, 'agents'), plan.skillDir]) {
+      try {
+        rmdirSync(dir);
+      } catch {
+        // the folder holds something else, which stays
+      }
+    }
+  }
+}
+
+// For doctor: which of Carwash's Codex hooks are in the hooks file, and which
+// of those Codex has been told to trust. Codex keys each approval by the file,
+// the event, and the hook's place in the file.
+export function codexHooksCheck(env = process.env) {
+  const file = resolveSettingsFile(codexHooksPath(env));
+  let data;
+  try {
+    data = readSettings(file).data;
+  } catch {
+    return { readable: false, file };
+  }
+  let config = '';
+  try {
+    config = readFileSync(codexConfigPath(env), 'utf8');
+  } catch {
+    // no approvals yet
+  }
+  const snake = (event) => event.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+  // Codex may name the file as configured or with links resolved, and TOML
+  // doubles the backslashes in a Windows path.
+  const names = [...new Set([codexHooksPath(env), file])].flatMap((name) => [name, name.replace(/\\/g, '\\\\')]);
+  const keyed = (key) => names.some((name) => config.includes(`[hooks.state."${name}${key}"]`));
+  const result = { readable: true, file, hooks: {}, trusted: {}, nodes: [] };
+  for (const event of Object.keys(CODEX_HOOKS)) {
+    const groups = Array.isArray(data?.hooks?.[event]) ? data.hooks[event] : [];
+    result.hooks[event] = false;
+    result.trusted[event] = false;
+    groups.forEach((group, g) => {
+      (Array.isArray(group?.hooks) ? group.hooks : []).forEach((hook, h) => {
+        if (!isCarwashCodexHook(hook?.command)) return;
+        result.hooks[event] = true;
+        result.nodes.push(hook.command);
+        if (keyed(`:${snake(event)}:${g}:${h}`)) result.trusted[event] = true;
+      });
+    });
+  }
+  return result;
+}
+
+export const codexSkillInstalled = (env = process.env) => isOurSkill(join(codexSkillDir(env), 'SKILL.md'));

package/src/install/doctor.mjs

@@ -6,6 +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 { codexDetected, codexHooksCheck, codexSkillInstalled } from './codex.mjs';
 import { commandProgram, isCarwashCommand, isCarwashHook } from './install.mjs';
 import { UPDATE_COMMAND } from './notice.mjs';
 import { readSettings, resolveSettingsFile } from './settings.mjs';
@@ -33,6 +34,21 @@ export function claudeVersion({ env = process.env, platform = process.platform }
   }
 }
 
+// Codex's own version, or null if `codex` is not on PATH.
+export function codexVersion({ env = process.env, platform = process.platform } = {}) {
+  try {
+    const result = spawnSync('codex', ['--version'], { env, encoding: 'utf8', timeout: 5000, shell: platform === 'win32', windowsHide: true });
+    const out = (result.stdout ?? '').trim();
+    return result.status === 0 && out ? out.split('\n')[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+// Whether doctor has anything to say about Codex: it is set up here, or an
+// install covered it.
+export const codexInScope = (env = process.env, record = readJson(installRecordPath(env))) => Boolean(record?.codex) || codexDetected(env);
+
 // The last few entries of the error log, newest last. Each entry starts with
 // the time it was written; a stack trace follows on the next lines.
 export function recentErrors(env = process.env) {
@@ -81,8 +97,9 @@ const date = (iso) => {
 
 // `running` is this copy's version, which under npx may differ from the copy
 // installed in ~/.carwash/app. `newest` is what npm said just now: { latest,
-// warning } or null.
-export function doctorReport({ env = process.env, now = Date.now(), running, newest, claude, platform = process.platform }) {
+// warning } or null. `claude` and `codex` are the tools' versions, or null;
+// `codex` is only asked for when Codex is in scope.
+export function doctorReport({ env = process.env, now = Date.now(), running, newest, claude, codex = null, platform = process.platform }) {
   const row = (label, value) => `  ${label.padEnd(18)}${value}`;
   const record = readJson(installRecordPath(env));
   const installed = typeof record?.version === 'string' ? record.version : null;
@@ -103,19 +120,43 @@ export function doctorReport({ env = process.env, now = Date.now(), running, new
   out.push(row('Node', process.version));
   out.push(row('System', `${platform} ${release()} ${arch()}`));
   out.push(row('Claude Code', claude ?? 'not found on PATH'));
+  const withCodex = codexInScope(env, record);
+  if (withCodex) out.push(row('Codex', codex ?? 'not found on PATH'));
 
   if (installed) {
-    const check = settingsCheck(env);
     const yes = (ok) => (ok ? 'ok' : 'MISSING');
-    if (!check.readable) {
-      out.push(row('Settings', `could not read ${tilde(settingsPath(env))}`));
-    } 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));
+    // Installs from before Codex support do not list their tools: Claude Code.
+    const tools = Array.isArray(record.tools) ? record.tools : ['claude'];
+    const nodes = [];
+    if (tools.includes('claude')) {
+      const check = settingsCheck(env);
+      if (!check.readable) {
+        out.push(row('Settings', `could not read ${tilde(settingsPath(env))}`));
+      } else {
+        out.push(row('Status line', yes(check.statusLine)));
+        out.push(row('Hooks', HOOK_EVENTS.map((event) => `${event} ${yes(check.hooks[event])}`).join(' · ')));
+        nodes.push(...check.nodes);
+      }
+      out.push(row('/wash command', yes(existsSync(join(skillDir(env), 'SKILL.md')))));
+    }
+    if (tools.includes('codex')) {
+      const check = codexHooksCheck(env);
+      if (!check.readable) {
+        out.push(row('Codex hooks', `could not read ${tilde(check.file)}`));
+      } else {
+        const events = Object.keys(check.hooks);
+        out.push(row('Codex hooks', events.map((event) => `${event} ${yes(check.hooks[event])}`).join(' · ')));
+        const present = events.filter((event) => check.hooks[event]);
+        if (present.length) {
+          const trusted = present.every((event) => check.trusted[event]);
+          out.push(row('Codex trust', trusted ? 'ok' : 'not yet: start Codex and choose "Trust all and continue" when it asks about new hooks'));
+        }
+        nodes.push(...check.nodes.map(commandProgram).filter(Boolean));
+      }
+      out.push(row('$wash command', yes(codexSkillInstalled(env))));
     }
-    out.push(row('/wash command', yes(existsSync(join(skillDir(env), 'SKILL.md')))));
+    const node = nodeRow([...new Set(nodes)]);
+    if (node) out.push(row('Node for Carwash', node));
     let waiting = '?';
     let written = '?';
     try {