codehere 2.0.0-beta.1 → 2.0.0-beta.2

package/README.md

@@ -2,7 +2,7 @@
 
 **A team brain for vibe coders.** It stops your AI coding agent from going in circles, checks "done" for real, and shares what your team learns. It works through plain files in git.
 
-Codehere is built to remove work, not add it. You keep using Claude Code as usual. Codehere talks to the agent, not to you, and stays silent unless it helps.
+Codehere is built to remove work, not add it. You keep using Claude Code or Codex CLI as usual. Codehere talks to the agent, not to you, and stays silent unless it helps.
 
 ## What it does
 
@@ -23,13 +23,19 @@ Codehere is built to remove work, not add it. You keep using Claude Code as usua
 ```bash
 npm install -g codehere@next   # the 2.0 beta; codehere@latest is still 1.x
 cd your-project
-codehere init               # finds your test command, adds hooks to .claude/settings.json, asks you to approve the command
-git add .codehere .claude/settings.json .gitignore
+codehere init --agent claude,codex   # finds your test command, adds the hooks, asks you to approve the command
+git add .codehere .claude/settings.json .codex/hooks.json .gitignore
 git commit -m "Add Codehere" && git push
 ```
 
+Use `--agent claude` or `--agent codex` for one agent; with no `--agent`, `init` sets up Claude Code. The hooks go in `.claude/settings.json` and `.codex/hooks.json`.
+
 Each teammate installs the CLI once (`npm install -g codehere@next`) and runs `codehere approve` once in the repo. Until they do, their agent tells them at session start that the test check is off. The hooks and the brain arrive through git.
 
+Codex runs a repo's hooks only after each developer trusts them. Open Codex in the repo, trust the project if asked, then type `/hooks` and trust the four Codehere hooks. Do it once per clone, and again after an update that changes the hooks. Until then Codex skips them, and `codex exec` does not warn.
+
+`codehere uninstall` removes the hooks, and `.codehere/` too when it holds no rules, lessons, help cards or briefs.
+
 The test command is in `.codehere/config.json`, which anyone with push access can change. So Codehere runs it only after you approve that exact command on your machine, at your terminal. If a pull or the agent changes it, the finish check skips it and tells you, until you approve it again. Approvals are kept in `~/.config/codehere/approvals.json`, outside the repo, so nothing that arrives through git can approve a command.
 
 ## The team loop
@@ -61,11 +67,30 @@ codehere ✓ npm test · 48 passed · re-run here · 6.2 s
 
 Don't want to commit help cards? Copy the printed text into WhatsApp, Discord or Slack instead.
 
+## Which agents
+
+| | Claude Code | Codex CLI |
+|---|---|---|
+| Team rules at session start | yes | yes |
+| A teammate's lesson after a failed command | yes | yes |
+| "Same error 3 times: stop and find the root cause" | yes | yes, given next to the error output |
+| Context added to a short prompt such as "still broken" | yes | yes |
+| Finish check: your tests re-run, the agent sent back | yes | yes |
+| Your one line (✓ ✕ ⊘ ›) | yes | in the interactive screen, as `↳ Hook · codehere ✓ …`; not in `codex exec` |
+| Restart-brief suggestion in long sessions | yes | no |
+| Before it works | nothing | each developer trusts the hooks in `/hooks` |
+| MCP tools, instruction file | no | no |
+| Tested on | 2.1.311 with haiku: [result](docs/conformance/2026-10-27-claude-2.1.311-haiku.md) | 0.164.0 with a local model (Qwen 3.5 9B through Ollama): [result](docs/conformance/2026-10-27-codex-0.164.0-qwen3.5-9b-q4-K-M.md) |
+
+The rows for rules, lessons and the finish check are checked on the real agent by `node scripts/conformance.mjs`. The other rows are checked by `npm test` on hook inputs recorded from each agent.
+
 ## Commands
 
 ```
-codehere init [--test "npm test"]       set up (safe to run again)
+codehere init [--agent claude,codex] [--test "npm test"]
+                                        set up (safe to run again)
 codehere approve                        let the finish check run the test command on this machine
+codehere uninstall                      remove Codehere from this repo (asks first)
 codehere rule ["text"]                  add or list team rules
 codehere lesson ["problem" --fix "..."] add or list lessons
 codehere brief [--gemma]                restart brief for a fresh session
@@ -110,15 +135,17 @@ node demo/demo.mjs --step   # press Enter between scenes (good for a live talk)
 npm test                    # end-to-end checks
 ```
 
-## Known limits (2.0.0, not released yet)
+## Known limits (2.0 beta)
 
-- Claude Code only for now. Gemini CLI and Codex hooks are next.
+- Claude Code and Codex CLI. Copilot and OpenCode are next. See [Which agents](#which-agents) for what works on each.
 - Lessons match by error text. Very generic errors can bring up a lesson that doesn't fit, which is why the agent gets it as reference, not as an instruction.
 - Redaction catches common keys, tokens and emails. Always read a help card before sharing it.
 - The "done" check needs a test command. Without one, only the tampering check runs.
 - Approvals are per folder. Each git worktree or extra clone needs its own `codehere approve`.
-- Approving `npm test` approves that command, not the scripts behind it in `package.json`. And Claude Code runs any hook a teammate adds to the committed `.claude/settings.json`. Both are your repo's code, with the same trust as running it yourself.
-- When the agent changes `.codehere/config.json`, `.codehere/rules.md` or the hook and env settings in `.claude/settings*.json` during a session, the finish check tells you. It cannot tell you if the session ends without a finish check, for example when you close it mid-turn. An agent that sets out to fake your terminal or rewrite Codehere's local files can also get around this.
+- In `codex exec`, Codex shows you none of Codehere's lines. The agent still gets every message, and the finish check still sends it back.
+- `codehere approve` and `codehere uninstall` ask only in your own terminal. They refuse when Claude Code or Codex is among the processes above them, and inside Codex's sandbox. An agent that detaches its terminal on purpose can still answer, so the finish check of a session that was open tells you when an approval or an uninstall happened.
+- Approving `npm test` approves that command, not the scripts behind it in `package.json`. And Claude Code runs any hook a teammate adds to the committed `.claude/settings.json`; Codex asks each developer to trust a new or changed hook first. Both are your repo's code, with the same trust as running it yourself.
+- When the agent changes `.codehere/config.json`, `.codehere/rules.md`, the hook and env settings in `.claude/settings*.json`, or `.codex/hooks.json` or `.codex/config.toml` during a session, the finish check tells you. It cannot tell you if the session ends without a finish check, for example when you close it mid-turn. An agent that sets out to fake your terminal or rewrite Codehere's local files can also get around this.
 - Only the test command needs approval. A teammate who sets `verifyOnStop` to `false` in `.codehere/config.json` turns the finish check off for everyone; `codehere status` shows it as off.
 - Sharing is through git. There is no server, so teammates see updates after `git pull`.
 - Prompt checks are plain word lists (English and Indonesian). They can miss a short prompt in another language.

package/bin/codehere.js

@@ -8,7 +8,9 @@ const flags = {};
 const pos = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
-  if (a.startsWith('--')) {
+  if (a.startsWith('--') && a.indexOf('=') > 2) {
+    flags[a.slice(2, a.indexOf('='))] = a.slice(a.indexOf('=') + 1);
+  } else if (a.startsWith('--')) {
     const key = a.slice(2);
     const next = argv[i + 1];
     if (!BOOLEAN.has(key) && next !== undefined && !next.startsWith('--')) {
@@ -23,8 +25,10 @@ const [command, ...rest] = pos;
 const USAGE = `codehere · a git-native team brain for vibe coders
 
 Setup
-  codehere init [--test "npm test"]   set up .codehere/ and Claude Code hooks
+  codehere init [--agent claude,codex] [--test "npm test"]
+                                      set up .codehere/ and the agents' hooks (default: Claude Code)
   codehere approve                    let the finish check run the test command on this machine
+  codehere uninstall                  remove Codehere's hooks, and .codehere/ if it holds no team content
 
 Team brain
   codehere rule ["text"]              add a team rule (or list rules)
@@ -43,18 +47,20 @@ When you're stuck
   codehere status                     what Codehere has seen
   codehere stats                      turns to green, loops stopped, session size
 
-Hooks (called by Claude Code, not by you)
-  codehere hook session-start | prompt | post-tool | stop
+Hooks (called by the agent, not by you)
+  codehere hook session-start | prompt | post-tool | stop [--agent codex]
 `;
 
 const run = async () => {
   switch (command) {
     case 'hook':
-      return runHook(rest[0]);
+      return runHook(rest[0], flags.agent);
     case 'init':
       return cmd.init(flags);
     case 'approve':
       return cmd.approve();
+    case 'uninstall':
+      return cmd.uninstall();
     case 'rule':
     case 'rules':
       return cmd.rule(rest.join(' '));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.2",
   "description": "A git-native team brain for vibe coders. Silent fixes for AI coding agents: breaks doom loops, verifies 'done', blocks test tampering, and shares what your team learned.",
   "repository": {
     "type": "git",

package/src/brain.js

@@ -227,6 +227,37 @@ export function addApproval(root, command) {
   return true;
 }
 
+export function removeApprovals(root) {
+  const file = approvalsFile(root);
+  const all = readAllApprovals(root);
+  if (!file || !(repoKey(root) in all.repos)) return;
+  delete all.repos[repoKey(root)];
+  fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n');
+}
+
+// uninstall leaves a note here, outside the repo. A session that was open when it ran still has
+// its hooks loaded, but its state and maybe .codehere/ are gone: its finish check reads the note.
+export function markRemoved(root, removed = true) {
+  const file = approvalsFile(root);
+  const all = readAllApprovals(root);
+  const notes = all.removed && typeof all.removed === 'object' ? all.removed : {};
+  if (!file || (!removed && !(repoKey(root) in notes))) return;
+  if (removed) notes[repoKey(root)] = new Date().toISOString();
+  else delete notes[repoKey(root)];
+  all.removed = notes;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n');
+}
+
+// When uninstall ran for dir or a folder above it, else null.
+export function removedAt(dir) {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    const at = readAllApprovals(d).removed?.[repoKey(d)];
+    if (typeof at === 'string') return at;
+    if (path.dirname(d) === d) return null;
+  }
+}
+
 // Control, format (bidi, zero-width), filler and variation characters escaped, so text from the repo cannot print a fake
 // line, move the cursor or hide part of a command.
 const ESCAPES = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };

package/src/commands.js

@@ -2,10 +2,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import readline from 'node:readline/promises';
+import { execFileSync } from 'node:child_process';
 import {
   findRoot, paths, ensureDirs, readConfig, writeConfig, readState, writeState,
   readRules, listDocs, parseDoc, renderDoc, slug, stamp, today, git, isGitRepo, me,
-  readApprovals, isApproved, addApproval, printable, commitId,
+  readApprovals, isApproved, addApproval, removeApprovals, markRemoved, printable, commitId,
 } from './brain.js';
 import { redact } from './signals.js';
 import { summarize } from './gemma.js';
@@ -19,6 +20,21 @@ const HOOK_EVENTS = {
   Stop: { cmd: 'codehere hook stop', timeout: 180 },
 };
 
+// Keep these strings stable: Codex asks every developer to trust a hook again when its definition changes.
+const CODEX_HOOK_EVENTS = {
+  SessionStart: { cmd: 'codehere hook session-start --agent codex' },
+  UserPromptSubmit: { cmd: 'codehere hook prompt --agent codex', timeout: 10 },
+  PostToolUse: { cmd: 'codehere hook post-tool --agent codex', matcher: 'Bash' },
+  Stop: { cmd: 'codehere hook stop --agent codex', timeout: 180 },
+};
+
+const AGENTS = {
+  claude: { name: 'Claude Code', file: '.claude/settings.json', events: HOOK_EVENTS },
+  codex: { name: 'Codex CLI', file: '.codex/hooks.json', events: CODEX_HOOK_EVENTS },
+};
+
+const ours = (h) => typeof h?.command === 'string' && h.command.startsWith('codehere hook ');
+
 function requireRoot() {
   const root = findRoot();
   if (!root) {
@@ -41,18 +57,18 @@ function detectTestCommand(root) {
   return null;
 }
 
-function mergeClaudeSettings(root) {
-  const dir = path.join(root, '.claude');
-  const file = path.join(dir, 'settings.json');
-  fs.mkdirSync(dir, { recursive: true });
+// Claude Code's .claude/settings.json and Codex's .codex/hooks.json share this shape.
+function mergeHooks(root, agent) {
+  const file = path.join(root, agent.file);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
   let settings = {};
   try {
     settings = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch {}
   settings.hooks = settings.hooks || {};
-  for (const [event, spec] of Object.entries(HOOK_EVENTS)) {
+  for (const [event, spec] of Object.entries(agent.events)) {
     const list = (settings.hooks[event] = settings.hooks[event] || []);
-    const already = list.some((g) => (g.hooks || []).some((h) => h.command === spec.cmd));
+    const already = list.some((g) => (g?.hooks || []).some((h) => h?.command === spec.cmd));
     if (already) continue;
     const hook = { type: 'command', command: spec.cmd };
     if (spec.timeout) hook.timeout = spec.timeout;
@@ -61,7 +77,55 @@ function mergeClaudeSettings(root) {
     list.push(group);
   }
   fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return file;
+}
+
+// Takes Codehere's hooks out of the agent's settings file, keeping everything else.
+// A file left with nothing in it is removed, and its folder if that is then empty.
+function removeHooks(root, agent) {
+  const file = path.join(root, agent.file);
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return false;
+  }
+  const hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+  let found = false;
+  for (const event of Object.keys(hooks)) {
+    if (!Array.isArray(hooks[event])) continue;
+    hooks[event] = hooks[event]
+      .filter((g) => g && typeof g === 'object')
+      .map((g) => {
+        const all = Array.isArray(g.hooks) ? g.hooks : [];
+        const kept = all.filter((h) => !ours(h));
+        if (kept.length !== all.length) found = true;
+        return { ...g, hooks: kept };
+      })
+      .filter((g) => g.hooks.length);
+    if (!hooks[event].length) delete hooks[event];
+  }
+  if (!found) return false;
+  if (!Object.keys(hooks).length) delete settings.hooks;
+  if (Object.keys(settings).length) {
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  } else {
+    fs.rmSync(file);
+    try {
+      fs.rmdirSync(path.dirname(file));
+    } catch {} // not empty: something else lives there
+  }
+  return true;
+}
+
+function installedAgents(root) {
+  return Object.values(AGENTS).filter((a) => {
+    try {
+      const hooks = JSON.parse(fs.readFileSync(path.join(root, a.file), 'utf8')).hooks || {};
+      return Object.values(hooks).some((gs) => Array.isArray(gs) && gs.some((g) => Array.isArray(g?.hooks) && g.hooks.some(ours)));
+    } catch {
+      return false;
+    }
+  });
 }
 
 function addGitignore(root) {
@@ -75,9 +139,29 @@ function addGitignore(root) {
 
 // ---------- approving the test command (this machine only) ----------
 
-// Approval needs a terminal. An agent's shell tool has none, though an agent that fakes one
-// can answer, so an approval made during a session is reported at the finish check.
-const atTerminal = () => !!(process.stdin.isTTY && process.stdout.isTTY);
+// Approving and uninstalling need the developer's own terminal: a terminal on stdin and stdout,
+// and no agent among the processes above this one. An agent's commands run under its process,
+// even in a terminal it opens (Codex can). Inside Codex's sandbox ps is not allowed, so the
+// parents cannot be read, which counts as under an agent. An agent that detaches its terminal
+// on purpose can still answer, so the finish check reports an approval or an uninstall.
+const AGENT_PROCESSES = new Set(['claude', 'codex', 'copilot', 'opencode']);
+const PS = fs.existsSync('/bin/ps') ? '/bin/ps' : '/usr/bin/ps';
+function underAgent() {
+  let pid = process.ppid;
+  for (let i = 0; i < 100 && pid > 1; i++) {
+    let line;
+    try {
+      line = execFileSync(PS, ['-o', 'ppid=,comm=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {
+      return true;
+    }
+    const m = /^(\d+)\s+(.+)$/.exec(line);
+    if (!m || AGENT_PROCESSES.has(path.basename(m[2]).toLowerCase())) return true;
+    pid = Number(m[1]);
+  }
+  return pid > 1;
+}
+const atTerminal = () => !!(process.stdin.isTTY && process.stdout.isTTY) && !underAgent();
 
 async function askApproval(root, command) {
   const last = git(root, 'log -1 --format="%an on %ad (%h)" --date=short -- .codehere/config.json');
@@ -108,7 +192,7 @@ export async function approve() {
   if (!command) return console.log('No test command set. Set one: codehere init --test "npm test"');
   if (isApproved(root, command)) return console.log(`Already approved on this machine: ${printable(command)}`);
   if (!atTerminal()) {
-    console.error('codehere approve asks you to confirm at a terminal. Run it in your own terminal.');
+    console.error('codehere approve asks you to confirm in your own terminal, not through an agent. Run it there.');
     process.exit(1);
   }
   await askApproval(root, command);
@@ -116,7 +200,27 @@ export async function approve() {
 
 // ---------- init ----------
 
+const RULES_MD = '# Team rules\n\nOne rule per line, starting with "- ". Written by people, not by the agent.\nEvery agent session on this repo loads these.\n\n';
+const README_MD = [
+  '# .codehere — this team\'s brain',
+  '',
+  'Plain markdown, shared through git. Commit and push it like code.',
+  '',
+  '- `rules.md`: team rules every agent session loads',
+  '- `lessons/`: errors someone already solved; shown to the agent only when the same error appears',
+  '- `help/`: help cards; teammates see them with `codehere inbox`',
+  '- `briefs/`: restart briefs for fresh sessions',
+  '- `local/`: this machine only (git-ignored)',
+  '',
+].join('\n');
+
 export async function init(flags) {
+  const names = flags.agent === undefined ? ['claude'] : String(flags.agent === true ? '' : flags.agent).split(',').map((x) => x.trim().toLowerCase());
+  if (!names.every((n) => Object.hasOwn(AGENTS, n))) {
+    console.error(`Unknown agent "${printable(flags.agent === true ? '' : flags.agent)}". Use --agent claude, --agent codex or --agent claude,codex.`);
+    process.exit(1);
+  }
+  const agents = [...new Set(names)].map((n) => AGENTS[n]);
   const root = process.cwd();
   const p = ensureDirs(root);
   const cfg = readConfig(root);
@@ -124,37 +228,19 @@ export async function init(flags) {
   else if (!cfg.testCommand) cfg.testCommand = detectTestCommand(root);
   writeConfig(root, cfg);
 
-  if (!fs.existsSync(p.rules)) {
-    fs.writeFileSync(
-      p.rules,
-      '# Team rules\n\nOne rule per line, starting with "- ". Written by people, not by the agent.\nEvery agent session on this repo loads these.\n\n'
-    );
-  }
-  fs.writeFileSync(
-    path.join(p.base, 'README.md'),
-    [
-      '# .codehere — this team\'s brain',
-      '',
-      'Plain markdown, shared through git. Commit and push it like code.',
-      '',
-      '- `rules.md`: team rules every agent session loads',
-      '- `lessons/`: errors someone already solved; shown to the agent only when the same error appears',
-      '- `help/`: help cards; teammates see them with `codehere inbox`',
-      '- `briefs/`: restart briefs for fresh sessions',
-      '- `local/`: this machine only (git-ignored)',
-      '',
-    ].join('\n')
-  );
+  if (!fs.existsSync(p.rules)) fs.writeFileSync(p.rules, RULES_MD);
+  fs.writeFileSync(path.join(p.base, 'README.md'), README_MD);
   for (const d of [p.lessons, p.help, p.briefs]) {
     const keep = path.join(d, '.gitkeep');
     if (!fs.existsSync(keep)) fs.writeFileSync(keep, '');
   }
   addGitignore(root);
-  const settingsFile = mergeClaudeSettings(root);
+  for (const a of agents) mergeHooks(root, a);
+  markRemoved(root, false);
 
   console.log('Codehere is set up.');
   console.log(`- Team brain: ${path.relative(root, p.base)}/`);
-  console.log(`- Claude Code hooks: ${path.relative(root, settingsFile)}`);
+  for (const a of agents) console.log(`- ${a.name} hooks: ${a.file}`);
   console.log(`- Test check on "done": ${cfg.testCommand ? printable(cfg.testCommand) : 'none found (set one with: codehere init --test "npm test")'}`);
   console.log('');
   if (cfg.testCommand && !isApproved(root, cfg.testCommand)) {
@@ -162,8 +248,83 @@ export async function init(flags) {
     else console.log('The test command runs only after you approve it on this machine: codehere approve');
     console.log('');
   }
-  console.log('Next: commit .codehere/ and .claude/settings.json so your team gets it too.');
-  console.log('Then just use Claude Code as usual. Codehere stays quiet unless it helps.');
+  if (agents.includes(AGENTS.codex)) {
+    console.log("Codex runs a repo's hooks only after each developer trusts them. Open Codex here, trust the project if asked,");
+    console.log('then type /hooks and trust the four Codehere hooks. Until then Codex skips them, and `codex exec` does not warn.');
+    console.log('');
+  }
+  console.log(`Next: commit .codehere/ and ${agents.map((a) => a.file).join(' and ')} so your team gets it too.`);
+  console.log(`Then just use ${agents.map((a) => a.name).join(' or ')} as usual. Codehere stays quiet unless it helps.`);
+}
+
+// ---------- uninstall ----------
+
+function removeGitignoreLine(root) {
+  const file = path.join(root, '.gitignore');
+  if (!fs.existsSync(file)) return;
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  const kept = lines.filter((l) => l !== '.codehere/local/');
+  if (kept.length === lines.length) return;
+  if (kept.join('\n').trim()) fs.writeFileSync(file, kept.join('\n'));
+  else fs.rmSync(file);
+}
+
+function filesIn(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const f = path.join(dir, e.name);
+    return e.isDirectory() ? filesIn(f) : [f];
+  });
+}
+
+const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// Like approve, it needs the developer's own terminal, so the agent cannot switch Codehere off.
+// .codehere/ goes only when it holds nothing but what init wrote.
+export async function uninstall() {
+  const root = findRoot();
+  if (!root) {
+    console.error('No .codehere folder here. Nothing to remove.');
+    process.exit(1);
+  }
+  // findRoot walks up: from a folder with no .codehere/ it can reach the home folder
+  const home = fs.realpathSync(root) === fs.realpathSync(os.homedir());
+  if (home || !isGitRepo(root)) {
+    console.error(`The nearest .codehere/ is in ${printable(root)}, ${home ? 'your home folder' : 'which is not a git repo'}. Nothing removed.`);
+    process.exit(1);
+  }
+  if (!atTerminal()) {
+    console.error('codehere uninstall asks you to confirm in your own terminal, not through an agent. Run it there.');
+    process.exit(1);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(`Remove Codehere from ${printable(root)}? [y/N] `);
+  rl.close();
+  if (!/^y(es)?$/i.test(answer.trim())) return console.log('Nothing removed.');
+
+  for (const a of Object.values(AGENTS)) {
+    if (removeHooks(root, a)) console.log(`- Removed Codehere's hooks from ${a.file}`);
+  }
+  removeApprovals(root);
+  markRemoved(root);
+  const p = paths(root);
+  fs.rmSync(p.local, { recursive: true, force: true });
+  const readme = path.join(p.base, 'README.md');
+  const written = [p.config, p.rules, readme, ...[p.lessons, p.help, p.briefs].map((d) => path.join(d, '.gitkeep'))];
+  const rules = readRules(root).length;
+  const docs = [p.lessons, p.help, p.briefs].map((d) => listDocs(d).length);
+  const other = filesIn(p.base).filter((f) => !written.includes(f)).length - docs.reduce((a, b) => a + b, 0);
+  const edited = [[p.rules, RULES_MD], [readme, README_MD]].filter(([f, text]) => fs.existsSync(f) && fs.readFileSync(f, 'utf8') !== text).map(([f]) => path.basename(f));
+  const held = [[rules, 'rule'], [docs[0], 'lesson'], [docs[1], 'help card'], [docs[2], 'brief'], [other, 'other file']].filter(([n]) => n).map(([n, w]) => count(n, w));
+  if (!rules) held.push(...edited.map((f) => `an edited ${f}`));
+  else if (edited.includes('README.md')) held.push('an edited README.md');
+  if (!held.length) {
+    fs.rmSync(p.base, { recursive: true, force: true });
+    removeGitignoreLine(root); // kept otherwise: a session still open would write local/ again
+    console.log('- Removed .codehere/');
+  } else {
+    console.log(`- Kept .codehere/: it holds ${held.join(', ')}. Delete it yourself if the team no longer needs it.`);
+  }
+  console.log('Codehere is removed from this repo on this machine. Commit the changes so your team gets them too.');
 }
 
 // ---------- rules ----------
@@ -445,6 +606,7 @@ export function status() {
   const { state, s } = lastSession(root);
   const p = paths(root);
   console.log('Codehere status');
+  console.log(`- Agents: ${installedAgents(root).map((a) => a.name).join(', ') || 'none (codehere init --agent claude,codex)'}`);
   console.log(`- Team rules: ${readRules(root).length}`);
   console.log(`- Team lessons: ${listDocs(p.lessons).length}`);
   console.log(`- Open help requests: ${listDocs(p.help).filter((d) => d.meta.status === 'open').length}`);

package/src/hooks.js

@@ -1,5 +1,5 @@
-// Claude Code hook handlers. Every handler fails open: if anything goes wrong,
-// it exits 0 and the agent carries on as if Codehere were not installed.
+// Hook handlers for Claude Code and Codex CLI (--agent codex). Every handler fails open: if
+// anything goes wrong, it exits 0 and the agent carries on as if Codehere were not installed.
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
@@ -7,6 +7,7 @@ import { spawnSync } from 'node:child_process';
 import {
   findRoot, paths, readConfig, readState, writeState, session, readRules, renderDoc,
   listDocs, git, isGitRepo, me, slug, today, isApproved, readApprovals, printable, commitId, statusFiles, gitHashes, noTick,
+  removedAt,
 } from './brain.js';
 import {
   responseText, signature, errorLines, similarity, tamperFindings, failingTest, lowInfoPrompt, vagueFeature, testCounts,
@@ -34,14 +35,20 @@ function toAgent(message) {
 
 const quiet = () => process.exit(0);
 
-export async function runHook(event) {
+export async function runHook(event, agent) {
   const input = readStdin();
-  const root = findRoot(input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd());
-  if (!root) quiet();
+  const start = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const root = findRoot(start);
+  if (!root) {
+    // uninstall ran while this session was open: its hooks still run, .codehere/ is gone
+    const at = event === 'stop' && removedAt(start);
+    if (at) emitJson({ systemMessage: removedLine(at) });
+    quiet();
+  }
   try {
     if (event === 'session-start') return sessionStart(root, input);
     if (event === 'prompt') return promptSubmit(root, input);
-    if (event === 'post-tool') return postTool(root, input);
+    if (event === 'post-tool') return postTool(root, input, agent === 'codex' ? 'codex' : 'claude');
     if (event === 'stop') return stop(root, input);
   } catch (err) {
     if (process.env.CODEHERE_DEBUG) console.error(err);
@@ -118,7 +125,7 @@ function briefFile(root, file) {
 
 // ---------- what changed in THIS session ----------
 
-const IGNORE = (f) => f.startsWith('.codehere/') || f.startsWith('.claude/');
+const IGNORE = (f) => f.startsWith('.codehere/') || f.startsWith('.claude/') || f.startsWith('.codex/');
 
 export function dirtySnapshot(root) {
   const files = statusFiles(root).filter((f) => !IGNORE(f));
@@ -146,10 +153,10 @@ function changedThisSession(root, s) {
   return [...changed];
 }
 
-// Files that decide what Codehere runs and tells every agent, and the agent's own hook
-// settings. Claude Code loads hooks at session start, so a hook removed mid-session
+// Files that decide what Codehere runs and tells every agent, and the agents' own hook
+// settings. Claude Code and Codex load hooks at session start, so a hook removed mid-session
 // still runs at this session's finish check and can report it.
-const PROTECTED = ['.codehere/config.json', '.codehere/rules.md', '.claude/settings.json', '.claude/settings.local.json'];
+const PROTECTED = ['.codehere/config.json', '.codehere/rules.md', '.claude/settings.json', '.claude/settings.local.json', '.codex/hooks.json', '.codex/config.toml'];
 
 function settingsSnapshot(root) {
   const snap = {};
@@ -161,6 +168,7 @@ function settingsSnapshot(root) {
     // In .claude/ only the hook and env settings count: Claude Code also saves permission
     // rules there when the developer picks "don't ask again". env can move HOME or
     // XDG_CONFIG_HOME, where approvals are kept. A missing file has none of them.
+    // Codex keeps what it saves in the user's own config, so .codex/ files count whole.
     if (f.startsWith('.claude/')) {
       try {
         const j = JSON.parse(text ?? '{}');
@@ -175,7 +183,8 @@ function settingsSnapshot(root) {
 function settingsChanged(root, s) {
   if (!s.settings) return []; // no snapshot from session start: cannot tell
   const now = settingsSnapshot(root);
-  return PROTECTED.filter((f) => now[f] !== s.settings[f]);
+  // a session that started before a file was protected has no hash for it
+  return PROTECTED.filter((f) => f in s.settings && now[f] !== s.settings[f]);
 }
 
 // ---------- PostToolUse (Bash): loop breaker + just-in-time team lessons ----------
@@ -291,7 +300,7 @@ function writeLesson(root, sig, proofCommand, changed) {
   return path.relative(root, file);
 }
 
-function postTool(root, input) {
+function postTool(root, input, agent) {
   if (input.tool_name && input.tool_name !== 'Bash') quiet();
   const command = (input.tool_input && input.tool_input.command) || '';
   if (readOnly(command)) quiet();
@@ -341,6 +350,14 @@ function postTool(root, input) {
         'or `codehere brief` to restart in a fresh session. Then wait for the user.'
       );
     }
+    // Codex replaces the command's output with a block's text (or exit 2's), so the agent
+    // would lose the error. There it goes in as context next to the output.
+    if (agent === 'codex') {
+      emitJson({
+        ...(lesson ? { systemMessage: lessonLine(lesson) } : {}),
+        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: msg.join('\n') },
+      });
+    }
     // with a lesson, JSON instead of exit 2, so the developer also gets its line
     if (lesson) emitJson({ decision: 'block', reason: msg.join('\n'), systemMessage: lessonLine(lesson) });
     toAgent(msg.join('\n') + '\n');
@@ -485,6 +502,8 @@ export function runResult(t) {
   return c && c.failed ? `${c.failed} failed` : `exit ${t.code}`;
 }
 
+const removedLine = (at) => `codehere ✕ codehere uninstall ran at ${new Date(at).toTimeString().slice(0, 5)} · this repo's checks are removed`;
+
 // message: the developer's lines, already escaped
 function block(reason, message) {
   emitJson(message ? { decision: 'block', reason, systemMessage: message } : { decision: 'block', reason });
@@ -500,7 +519,8 @@ function stop(root, input) {
   const base = commitId(s.startHead) || 'HEAD';
   const changed = changedThisSession(root, s);
   const settings = settingsChanged(root, s);
-  if (!changed.length && !settings.length) quiet(); // the agent changed nothing this session: stay silent
+  const removed = removedAt(root);
+  if (!changed.length && !settings.length && !removed) quiet(); // the agent changed nothing this session: stay silent
 
   // Lines for the developer. Each is escaped as a whole, so text from the repo cannot fake a
   // line, and text from the repo never carries a tick (noTick).
@@ -511,6 +531,7 @@ function stop(root, input) {
       if (a.at > (s.startedAt || '')) all.push(`codehere › approved on this machine during this session: ${noTick(a.command)}`);
     }
     if (settings.length) all.push(`codehere ✕ settings changed during this session · ${settings.join(' · ')}`);
+    if (removed) all.push(removedLine(removed));
     return all.map(printable).join('\n');
   }
   function report() {