codehere 2.0.0-beta.1 → 2.0.0-beta.3

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, Codex CLI or Copilot CLI as usual. Codehere talks to the agent, not to you, and stays silent unless it helps.
 
 ## What it does
 
@@ -23,13 +23,21 @@ 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,copilot   # finds your test command, adds the hooks, asks you to approve the command
+git add .codehere .claude/settings.json .codex/hooks.json .github/hooks/codehere.json .gitignore
 git commit -m "Add Codehere" && git push
 ```
 
+Name only the agents your team uses, such as `--agent claude` or `--agent codex,copilot`; with no `--agent`, `init` sets up Claude Code. The hooks go in `.claude/settings.json`, `.codex/hooks.json` and `.github/hooks/codehere.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.
+
+Copilot runs a repo's hooks only in a folder you trust: answer yes when Copilot asks on its first start in the repo. Copilot also runs the hooks in `.claude/settings.json`. Where `.github/hooks/codehere.json` runs Codehere, those stay quiet, so nothing runs twice; without it, they give Copilot the same checks.
+
+`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 +69,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 | Copilot CLI |
+|---|---|---|---|
+| Team rules at session start | yes | yes | yes |
+| A teammate's lesson after a failed command | yes | yes | yes |
+| "Same error 3 times: stop and find the root cause" | yes | yes, given next to the error output | yes, given next to the error output |
+| Context added to a short prompt such as "still broken" | yes | yes | no: by Copilot's docs it drops a prompt hook's output |
+| Finish check: your tests re-run, the agent sent back | yes | yes | yes |
+| Your one line (✓ ✕ ⊘ ›) | yes | in the interactive screen, as `↳ Hook · codehere ✓ …`; not in `codex exec` | no; when the agent is sent back, you see the full reason as the next prompt |
+| Restart-brief suggestion in long sessions | yes | no | no |
+| Before it works | nothing | each developer trusts the hooks in `/hooks` | each developer trusts the folder when Copilot asks |
+| MCP tools, instruction file | no | 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) | 1.0.105 with a local model (Qwen 3.5 9B through Ollama): [result](docs/conformance/2026-10-29-copilot-1.0.105-qwen3.5-9b-q4-K-M.md), and with only the Claude Code hooks installed: [result](docs/conformance/2026-10-29-copilot-1.0.105-qwen3.5-9b-q4-K-M-claude-hooks-only.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,copilot] [--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 +137,19 @@ 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, Codex CLI and Copilot CLI. OpenCode is next. Copilot in VS Code reads the same hook files but has not been checked, and Copilot's cloud agent is not supported. 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.
+- Copilot shows you none of Codehere's lines either, so on Copilot you do not see the ✓, the ⊘, or the notes about an approval, an uninstall or a settings change during a session. The agent still gets every message, and when the finish check sends it back you see the reason as the next prompt.
+- Copilot's cloud agent also runs the committed `.github/hooks/codehere.json`. `codehere` is not installed there, so by GitHub's docs each hook fails and the job carries on without Codehere.
+- `codehere approve` and `codehere uninstall` ask only in your own terminal. They refuse when Claude Code, Codex or Copilot 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 (not on Copilot, which shows none of these lines).
+- 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`, as Copilot does in a trusted folder for `.github/hooks/` and `.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 `.github/copilot/settings*.json`, or `.codex/hooks.json`, `.codex/config.toml` or `.github/hooks/codehere.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.
 - 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,copilot] [--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|copilot]
 `;
 
 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.3",
   "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,33 @@ 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 },
+};
+
+// Copilot's own format: camelCase events, hooks listed directly under each event, timeout as
+// timeoutSec. Its prompt output is dropped, so that hook only counts the turn.
+const COPILOT_HOOK_EVENTS = {
+  sessionStart: { cmd: 'codehere hook session-start --agent copilot' },
+  userPromptSubmitted: { cmd: 'codehere hook prompt --agent copilot', timeout: 10 },
+  postToolUse: { cmd: 'codehere hook post-tool --agent copilot', matcher: 'bash' },
+  agentStop: { cmd: 'codehere hook stop --agent copilot', 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 },
+  copilot: { name: 'Copilot CLI', file: '.github/hooks/codehere.json', events: COPILOT_HOOK_EVENTS, flat: true },
+};
+
+const ours = (h) => typeof h?.command === 'string' && h.command.startsWith('codehere hook ');
+// Claude Code and Codex wrap hooks in groups; Copilot lists each hook directly.
+const hooksOf = (g) => (Array.isArray(g?.hooks) ? g.hooks : [g]);
+
 function requireRoot() {
   const root = findRoot();
   if (!root) {
@@ -41,27 +69,84 @@ 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 });
+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 {}
+  if (agent.flat) settings = { version: 1, ...settings };
   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) => hooksOf(g).some((h) => h?.command === spec.cmd));
     if (already) continue;
     const hook = { type: 'command', command: spec.cmd };
+    if (agent.flat) {
+      if (spec.matcher) hook.matcher = spec.matcher;
+      if (spec.timeout) hook.timeoutSec = spec.timeout;
+      list.push(hook);
+      continue;
+    }
     if (spec.timeout) hook.timeout = spec.timeout;
     const group = { hooks: [hook] };
     if (spec.matcher) group.matcher = spec.matcher;
     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 folders up to the repo if they are 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')
+      .flatMap((g) => {
+        if (!Array.isArray(g.hooks)) return ours(g) ? ((found = true), []) : [g];
+        const kept = g.hooks.filter((h) => !ours(h));
+        if (kept.length !== g.hooks.length) found = true;
+        return kept.length ? [{ ...g, hooks: kept }] : [];
+      });
+    if (!hooks[event].length) delete hooks[event];
+  }
+  if (!found) return false;
+  if (!Object.keys(hooks).length) delete settings.hooks;
+  if (Object.keys(settings).some((k) => !(agent.flat && k === 'version'))) {
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  } else {
+    fs.rmSync(file);
+    for (let d = path.dirname(file); d !== root; d = path.dirname(d)) {
+      try {
+        fs.rmdirSync(d);
+      } catch {
+        break; // 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) => hooksOf(g).some(ours)));
+    } catch {
+      return false;
+    }
+  });
 }
 
 function addGitignore(root) {
@@ -75,9 +160,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 +213,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 +221,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 with claude, codex or copilot, or several: --agent claude,codex,copilot.`);
+    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 +249,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 +269,87 @@ 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('');
+  }
+  if (agents.includes(AGENTS.copilot)) {
+    console.log("Copilot runs a repo's hooks only in a folder you trust. Answer yes when Copilot asks on its first start here.");
+    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 +631,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,6 @@
-// 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, Codex CLI (--agent codex) and Copilot CLI (--agent copilot).
+// 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 +8,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 +36,54 @@ function toAgent(message) {
 
 const quiet = () => process.exit(0);
 
-export async function runHook(event) {
-  const input = readStdin();
-  const root = findRoot(input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd());
-  if (!root) quiet();
+// Copilot's inputs: camelCase from its own hook file, snake_case from .claude/settings.json.
+// Map them to the names the handlers read. A failed command arrives as a successful tool
+// call; only its output shows the failure.
+function fromCopilot(i) {
+  const tool = i.toolName ?? i.tool_name;
+  return {
+    ...i,
+    session_id: i.sessionId ?? i.session_id,
+    tool_name: tool === 'bash' ? 'Bash' : tool,
+    tool_input: i.toolArgs ?? i.tool_input,
+    tool_response: i.toolResult?.textResultForLlm ?? i.tool_result?.text_result_for_llm,
+  };
+}
+
+const COPILOT_EVENT = { 'session-start': 'sessionStart', prompt: 'userPromptSubmitted', 'post-tool': 'postToolUse', stop: 'agentStop' };
+
+// Whether Copilot's own hook file runs Codehere for this event.
+function copilotFileRuns(root, event) {
+  try {
+    const hooks = JSON.parse(fs.readFileSync(path.join(root, '.github/hooks/codehere.json'), 'utf8')).hooks;
+    return (hooks?.[COPILOT_EVENT[event]] || []).some((h) => h?.command === `codehere hook ${event} --agent copilot`);
+  } catch {
+    return false;
+  }
+}
+
+export async function runHook(event, agent) {
+  let input = readStdin();
+  const start = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const root = findRoot(start);
+  // Copilot also runs the hooks in .claude/settings.json, adding a `timestamp` Claude Code does
+  // not send. When Copilot's own file runs Codehere for this event, these stay quiet so nothing
+  // runs twice. Otherwise they are all Copilot has, and answer in its format.
+  if (agent !== 'copilot' && process.env.COPILOT_CLI && 'timestamp' in input) {
+    if (root && copilotFileRuns(root, event)) quiet();
+    agent = 'copilot';
+  }
+  if (agent === 'copilot') input = fromCopilot(input);
+  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 === 'session-start') return sessionStart(root, input, agent);
     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' || agent === 'copilot' ? agent : 'claude');
     if (event === 'stop') return stop(root, input);
   } catch (err) {
     if (process.env.CODEHERE_DEBUG) console.error(err);
@@ -51,7 +93,7 @@ export async function runHook(event) {
 
 // ---------- SessionStart: load only human-confirmed context ----------
 
-function sessionStart(root, input) {
+function sessionStart(root, input, agent) {
   const state = readState(root);
   const s = session(state, input.session_id);
   s.transcript = input.transcript_path || s.transcript;
@@ -103,6 +145,8 @@ function sessionStart(root, input) {
   }
 
   writeState(root, state);
+  // Copilot reads only JSON here; Claude Code and Codex take the plain text
+  if (out.length && agent === 'copilot') emitJson({ additionalContext: out.join('\n') });
   if (out.length) process.stdout.write(out.join('\n') + '\n');
   quiet();
 }
@@ -118,7 +162,7 @@ function briefFile(root, file) {
 
 // ---------- what changed in THIS session ----------
 
-const IGNORE = (f) => f.startsWith('.codehere/') || f.startsWith('.claude/');
+const IGNORE = (f) => ['.codehere/', '.claude/', '.codex/', '.github/copilot/', '.github/hooks/'].some((d) => f.startsWith(d));
 
 export function dirtySnapshot(root) {
   const files = statusFiles(root).filter((f) => !IGNORE(f));
@@ -146,22 +190,35 @@ 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
-// 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'];
+// 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. Copilot runs every file in
+// .github/hooks/, so that folder counts as one.
+const PROTECTED = [
+  '.codehere/config.json', '.codehere/rules.md', '.claude/settings.json', '.claude/settings.local.json', '.codex/hooks.json', '.codex/config.toml',
+  '.github/hooks/', '.github/copilot/settings.json', '.github/copilot/settings.local.json',
+];
+
+function readProtected(root, f) {
+  if (!f.endsWith('/')) return fs.readFileSync(path.join(root, f), 'utf8');
+  const files = fs.readdirSync(path.join(root, f)).filter((n) => n.endsWith('.json')).sort();
+  if (!files.length) return null;
+  return files.map((n) => `${n}\0${fs.readFileSync(path.join(root, f, n), 'utf8')}`).join('\0');
+}
 
 function settingsSnapshot(root) {
   const snap = {};
   for (const f of PROTECTED) {
     let text = null;
     try {
-      text = fs.readFileSync(path.join(root, f), 'utf8');
+      text = readProtected(root, f);
     } catch {}
     // 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.
-    if (f.startsWith('.claude/')) {
+    // Codex keeps what it saves in the user's own config, so .codex/ files count whole.
+    // Copilot's settings files in .github/copilot/ count like .claude/; its hooks file is ours.
+    if (f.startsWith('.claude/') || f.startsWith('.github/copilot/')) {
       try {
         const j = JSON.parse(text ?? '{}');
         text = JSON.stringify([j.hooks ?? null, j.disableAllHooks ?? null, j.env ?? null]);
@@ -175,7 +232,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 +349,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,11 +399,22 @@ 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. Copilot shows
+    // exit 2 to the developer, not the agent, and takes context only in its own format.
+    if (agent === 'copilot') emitJson({ additionalContext: msg.join('\n') });
+    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');
   }
 
+  if (lesson && agent === 'copilot') emitJson({ additionalContext: lessonText(root, lesson) });
   if (lesson) {
     emitJson({
       systemMessage: lessonLine(lesson),
@@ -485,6 +554,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 +571,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 +583,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() {