Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(hosts): hooks.json installer — post-edit blast radius + auto-sync for CLI agents

Shrish Dwivedif0d3c50f7f40
diff --git a/src/hosts/codex-hooks.ts b/src/hosts/codex-hooks.ts
new file mode 100644
index 00000000..7befd7aa
--- /dev/null
+++ b/src/hosts/codex-hooks.ts
@@ -0,0 +1,67 @@
+/**
+ * Active-layer install for CLI agents that read user-level hooks.json with
+ * PostToolUse semantics. Writes the shared hook shim and one PostToolUse
+ * entry that runs post-edit + background sync after every file edit.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { hooksShim } from '../claude/shim-template.js';
+
+export interface HookWrite {
+ id: string;
+ path: string;
+ action: 'created' | 'updated' | 'unchanged' | 'skipped-unparseable';
+}
+
+function dirExists(p: string): boolean {
+ try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+function writeOwned(id: string, path: string, content: string, mode?: number): HookWrite {
+ const existed = existsSync(path);
+ if (existed && readFileSync(path, 'utf8') === content) return { id, path, action: 'unchanged' };
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, content);
+ if (mode !== undefined) chmodSync(path, mode);
+ return { id, path, action: existed ? 'updated' : 'created' };
+}
+
+function isGraftEntry(entry: unknown): boolean {
+ return JSON.stringify(entry).includes('graft-hooks.cjs');
+}
+
+export function installCodexHooks(home: string): HookWrite[] {
+ const base = join(home, '.codex');
+ if (!dirExists(base)) return [];
+
+ const shimPath = join(base, 'hooks', 'graft', 'graft-hooks.cjs');
+ const shimWrite = writeOwned('codex-hook-shim', shimPath, hooksShim(), 0o755);
+
+ const cfgPath = join(base, 'hooks.json');
+ let root: Record<string, any> = {};
+ const existed = existsSync(cfgPath);
+ if (existed) {
+ try { root = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch {
+ return [shimWrite, { id: 'codex-hooks', path: cfgPath, action: 'skipped-unparseable' }];
+ }
+ }
+ if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+ return [shimWrite, { id: 'codex-hooks', path: cfgPath, action: 'skipped-unparseable' }];
+ }
+ const before = JSON.stringify(root);
+ const hooks = (root.hooks ??= {});
+ if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
+ return [shimWrite, { id: 'codex-hooks', path: cfgPath, action: 'skipped-unparseable' }];
+ }
+ const prior: unknown[] = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
+ hooks.PostToolUse = [
+ ...prior.filter((e) => !isGraftEntry(e)),
+ {
+ matcher: 'Write|Edit|MultiEdit',
+ hooks: [{ type: 'command', command: `node "${shimPath}" post-edit-sync`, timeout: 10000 }],
+ },
+ ];
+ if (JSON.stringify(root) === before) return [shimWrite, { id: 'codex-hooks', path: cfgPath, action: 'unchanged' }];
+ writeFileSync(cfgPath, `${JSON.stringify(root, null, 2)}\n`);
+ return [shimWrite, { id: 'codex-hooks', path: cfgPath, action: existed ? 'updated' : 'created' }];
+}
diff --git a/test/hosts-codex-hooks.test.ts b/test/hosts-codex-hooks.test.ts
new file mode 100644
index 00000000..86621cdc
--- /dev/null
+++ b/test/hosts-codex-hooks.test.ts
@@ -0,0 +1,56 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { installCodexHooks } from '../src/hosts/codex-hooks.js';
+
+function fresh(): string { return mkdtempSync(join(tmpdir(), 'graft-cxhooks-')); }
+
+test('no-op when the CLI home dir is absent', () => {
+ assert.deepEqual(installCodexHooks(fresh()), []);
+});
+
+test('writes shim + hooks.json entry, idempotent on re-run', () => {
+ const home = fresh();
+ mkdirSync(join(home, '.codex'), { recursive: true });
+ const w = installCodexHooks(home);
+ assert.equal(w.length, 2);
+ const shim = join(home, '.codex', 'hooks', 'graft', 'graft-hooks.cjs');
+ assert.ok(existsSync(shim));
+ assert.ok(statSync(shim).mode & 0o111, 'shim is executable');
+ const cfg = JSON.parse(readFileSync(join(home, '.codex', 'hooks.json'), 'utf8'));
+ const entries = cfg.hooks.PostToolUse;
+ assert.equal(entries.length, 1);
+ assert.equal(entries[0].matcher, 'Write|Edit|MultiEdit');
+ assert.match(entries[0].hooks[0].command, /post-edit-sync/);
+ const again = installCodexHooks(home);
+ assert.deepEqual(again.map((x) => x.action), ['unchanged', 'unchanged']);
+ assert.equal(JSON.parse(readFileSync(join(home, '.codex', 'hooks.json'), 'utf8')).hooks.PostToolUse.length, 1);
+});
+
+test('foreign hook entries are preserved; stale graft entries replaced', () => {
+ const home = fresh();
+ mkdirSync(join(home, '.codex'), { recursive: true });
+ writeFileSync(join(home, '.codex', 'hooks.json'), JSON.stringify({
+ hooks: { PostToolUse: [
+ { matcher: 'Bash', hooks: [{ type: 'command', command: 'other-tool' }] },
+ { matcher: 'Write', hooks: [{ type: 'command', command: 'node /old/graft-hooks.cjs post-edit' }] },
+ ] },
+ }));
+ installCodexHooks(home);
+ const entries = JSON.parse(readFileSync(join(home, '.codex', 'hooks.json'), 'utf8')).hooks.PostToolUse;
+ assert.equal(entries.length, 2, 'foreign kept, stale graft replaced by fresh');
+ assert.ok(entries.some((e: any) => e.hooks[0].command === 'other-tool'));
+ assert.ok(entries.some((e: any) => /post-edit-sync/.test(JSON.stringify(e))));
+ assert.ok(!JSON.stringify(entries).includes('/old/'));
+});
+
+test('unparseable hooks.json is never rewritten', () => {
+ const home = fresh();
+ mkdirSync(join(home, '.codex'), { recursive: true });
+ writeFileSync(join(home, '.codex', 'hooks.json'), '{ nope');
+ const w = installCodexHooks(home);
+ assert.ok(w.some((x) => x.action === 'skipped-unparseable'));
+ assert.equal(readFileSync(join(home, '.codex', 'hooks.json'), 'utf8'), '{ nope');
+});