hookstack-cli 0.1.48 → 0.1.50

package/README.md

@@ -1,8 +1,8 @@
 # hookstack-cli
 
-**Install Claude Code hooks in one command.**
+**Install agentic hooks in one command — Claude Code, OpenAI Codex, or GitHub Copilot.**
 
-[hookstack.app](https://www.hookstack.app) — the community catalogue for Claude Code hooks. Browse, select, and wire them into your project with one command.
+[hookstack.app](https://www.hookstack.app) — the community catalogue for agentic hooks. Browse, select, and wire them into your project with one command. The same hooks install for any of the three supported agents; only the config file format differs.
 
 ---
 
@@ -22,35 +22,57 @@ That's it. The CLI fetches the hooks, shows you what will be installed, and patc
 npx hookstack-cli@latest install --hooks=<slug1>,<slug2>,...
 
 Options:
-  --hooks <slugs>   Comma-separated hook slugs (required)
-  --global, -g      Install into ~/.claude instead of ./.claude
-  --copilot         Install into ./.claude with paths adapted for GitHub Copilot
-  --scope <s>       "project" (default), "global", or "copilot"
-  --with-tests      Also install vitest unit tests into tests/hooks/ (project scope only)
-  --yes, -y         Skip prompts (non-interactive / CI)
-  --version, -v     Print version
-  --help, -h        Show help
+  --hooks <slugs>    Comma-separated hook slugs (required)
+  --project          Claude Code, this project — ./.claude (default)
+  --global, -g       Claude Code, all projects — ~/.claude
+  --codex-project    OpenAI Codex, this project — ./.codex/hooks.json (committed)
+  --codex-profile    OpenAI Codex, all projects — ~/.codex/hooks.json
+  --copilot          GitHub Copilot — ./.claude with paths adapted for Copilot
+  --scope <s>        "project" (default), "global", "copilot",
+                     "codex-project", or "codex-profile"
+  --with-tests       Also install vitest unit tests into tests/hooks/ (project scope only)
+  --yes, -y          Skip prompts (non-interactive / CI)
+  --version, -v      Print version
+  --help, -h         Show help
 ```
 
+### Target agents & scopes
+
+The hook code is identical across agents — only the config file it's wired into changes. Pick a target with a flag (or via the interactive menu):
+
+| Flag | Agent | Scope | Config file | Scripts dir |
+|---|---|---|---|---|
+| `--project` (default) | Claude Code | this project | `.claude/settings.json` | `.claude/hooks/` |
+| `--global`, `-g` | Claude Code | all projects | `~/.claude/settings.json` | `~/.claude/hooks/` |
+| `--codex-project` | OpenAI Codex | this project | `.codex/hooks.json` (committed) | `.codex/hooks/` |
+| `--codex-profile` | OpenAI Codex | all projects | `~/.codex/hooks.json` | `~/.codex/hooks/` |
+| `--copilot` | GitHub Copilot | this project | `.claude/` paths adapted | `.claude/hooks/` |
+
+Codex and Claude Code expose the same lifecycle event names (`PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`…), so a HookStack hook is portable between them without any change to the `.mjs` — the CLI just writes the appropriate config format.
+
 ### Interactive mode (default in a terminal)
 
 When run in a terminal the CLI opens an interactive prompt:
 
-1. Fetches the requested hooks from the registry
-2. Shows an **installation summary** (path, category, events, blocking flag)
-3. Shows a **security panel** (shell access · network · filesystem writes · Snyk score)
-4. Asks for confirmation before writing anything
+1. Asks which **target agent** to install for — the menu order is: This project → All my projects → Codex profile → Codex project → GitHub Copilot
+2. Fetches the requested hooks from the registry
+3. Shows an **installation summary** (path, category, events, blocking flag)
+4. Shows a **security panel** (shell access · network · filesystem writes · Snyk score)
+5. Asks for confirmation before writing anything
 
 ### Non-interactive mode (`--yes` or piped)
 
 Skips all prompts — useful in CI or dotfile bootstrap scripts.
 
 ```bash
-# CI bootstrap
+# CI bootstrap (Claude Code, project)
 npx hookstack-cli@latest install --hooks=pre-bash-secret-detection,pre-bash-guard-git-push-main --yes --scope=project
 
 # CI bootstrap with unit tests (avoids SonarQube gating on new files without tests)
 npx hookstack-cli@latest install --hooks=pre-bash-secret-detection,pre-bash-guard-git-push-main --yes --with-tests
+
+# CI bootstrap for OpenAI Codex (committed ./.codex/hooks.json)
+npx hookstack-cli@latest install --hooks=pre-bash-secret-detection,pre-bash-guard-git-push-main --yes --scope=codex-project
 ```
 
 ---
@@ -59,11 +81,11 @@ npx hookstack-cli@latest install --hooks=pre-bash-secret-detection,pre-bash-guar
 
 For each hook the CLI:
 
-- Writes the `.mjs` script to `.claude/hooks/` (or `~/.claude/hooks/` for global scope)
-- Patches `.claude/settings.json` to register the hook on the right lifecycle event
+- Writes the `.mjs` script to the scripts directory for the chosen agent (`.claude/hooks/`, `~/.claude/hooks/`, `.codex/hooks/`, or `~/.codex/hooks/`)
+- Patches the agent's config file (`.claude/settings.json` or `.codex/hooks.json`) to register the hook on the right lifecycle event
 - Optionally writes vitest unit tests to `tests/hooks/` when `--with-tests` is passed (or confirmed interactively)
 
-No new dependencies are added to your project. Hooks are plain Node.js scripts — no SDK, no agent modification.
+The same hook `.mjs` is used regardless of agent — Claude Code and Codex share lifecycle event names, so only the config file format changes. No new dependencies are added to your project. Hooks are plain Node.js scripts — no SDK, no agent modification.
 
 ---
 
@@ -92,7 +114,7 @@ Browse and filter the full catalogue at **[hookstack.app](https://www.hookstack.
 ## Requirements
 
 - Node.js ≥ 18
-- Claude Code installed (hooks are wired into its lifecycle)
+- One of the supported agents installed — Claude Code, OpenAI Codex, or GitHub Copilot (hooks are wired into the agent's lifecycle)
 
 ---
 

package/bin/cli

@@ -12,9 +12,11 @@ import {
   mergeHooks,
   assertSafeTarget,
   collectIncomingHooks,
+  resolveScriptPath,
   buildSecurityRows,
   buildPostInstallHints,
   doInstallTests,
+  isGlobalScope,
 } from './core.mjs'
 
 const API_BASE = process.env.HOOKSTACK_API_BASE || 'https://hookstack.vercel.app'
@@ -111,24 +113,31 @@ function doInstall(hooks, dirs, scope, log) {
   mkdirSync(dirs.claudeDir, { recursive: true })
   mkdirSync(dirs.hooksDir, { recursive: true })
 
+  const configName = dirs.format === 'codex' ? 'hooks.json' : 'settings.json'
   let settings = {}
   if (existsSync(dirs.settingsPath)) {
     try {
       settings = JSON.parse(readFileSync(dirs.settingsPath, 'utf8'))
     } catch {
-      log.warn('Could not parse existing settings.json — starting fresh')
+      log.warn(`Could not parse existing ${configName} — starting fresh`)
     }
   }
 
   const incoming = collectIncomingHooks(hooks, { scope, globalRoot: dirs.root })
-  settings.hooks = mergeHooks(settings.hooks ?? {}, incoming)
+  if (dirs.format === 'codex') {
+    // Codex hooks.json holds events at the top level (no "hooks" wrapper).
+    settings = mergeHooks(settings, incoming)
+  } else {
+    settings.hooks = mergeHooks(settings.hooks ?? {}, incoming)
+  }
   writeFileSync(dirs.settingsPath, JSON.stringify(settings, null, 2) + '\n')
 
   let scriptCount = 0
   for (const hook of hooks) {
     if (!hook.script_path || !hook.code_snippet) continue
-    assertSafeTarget(dirs.root, hook.script_path)
-    const dest = join(dirs.root, hook.script_path)
+    const target = resolveScriptPath(hook.script_path, scope)
+    assertSafeTarget(dirs.root, target)
+    const dest = join(dirs.root, target)
     mkdirSync(join(dest, '..'), { recursive: true })
     writeFileSync(dest, hook.code_snippet, 'utf8')
     scriptCount++
@@ -141,6 +150,15 @@ function doInstall(hooks, dirs, scope, log) {
 
 const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
 
+// Human-readable destination shown in the confirm prompt and result panel.
+const SCOPE_LABELS = {
+  project: './.claude',
+  global: '~/.claude',
+  copilot: './.claude (Copilot mode)',
+  'codex-project': './.codex/hooks.json (Codex)',
+  'codex-profile': '~/.codex/hooks.json (Codex)',
+}
+
 function onCancel() {
   p.cancel('Installation cancelled.')
   process.exit(0)
@@ -148,7 +166,7 @@ function onCancel() {
 
 async function interactiveInstall(slugs, args) {
   console.log('\n' + BANNER + '\n')
-  p.intro(pc.bold('hooks') + pc.dim(`  Claude Code hook installer  v${VERSION}`))
+  p.intro(pc.bold('hooks') + pc.dim(`  Agentic hook installer · Claude Code · Codex · Copilot  v${VERSION}`))
 
   // Fetch
   const spin = p.spinner()
@@ -173,18 +191,28 @@ async function interactiveInstall(slugs, args) {
     options: [
       {
         value: 'project',
-        label: 'This project',
-        hint: './.claude  —  committed with your repo',
+        label: 'Claude Code - This project',
+        hint: '<repo>/.claude',
       },
       {
         value: 'global',
-        label: 'All my projects',
-        hint: '~/.claude  —  every project on this machine',
+        label: 'Claude Code - Profile',
+        hint: '~/.claude/',
+      },
+      {
+        value: 'codex-project',
+        label: 'Codex - This project',
+        hint: '<repo>/.codex/',
+      },
+      {
+        value: 'codex-profile',
+        label: 'Codex - Profile',
+        hint: '~/.codex/',
       },
       {
         value: 'copilot',
-        label: 'GitHub Copilot project',
-        hint: './.claude  —  paths adapted for Copilot',
+        label: 'GitHub Copilot - This project',
+        hint: '<repo>/.claude/ Copilot compatible',
       },
     ],
     initialValue: scope,
@@ -199,7 +227,7 @@ async function interactiveInstall(slugs, args) {
   p.note(securityPanel(secRows), 'Installation Summary')
 
   // Confirm
-  const scopeLabel = scope === 'global' ? '~/.claude' : scope === 'copilot' ? './.claude (Copilot mode)' : './.claude'
+  const scopeLabel = SCOPE_LABELS[scope] ?? './.claude'
   const confirmed = await p.confirm({
     message: `Install ${plural(hooks.length, 'hook')} into ${pc.cyan(scopeLabel)}?`,
   })
@@ -220,7 +248,7 @@ async function interactiveInstall(slugs, args) {
   // Unit tests prompt (project/copilot scope only)
   let testResult = null
   const hooksWithTests = hooks.filter(h => h.test_snippet)
-  if (scope !== 'global' && hooksWithTests.length > 0) {
+  if (!isGlobalScope(scope) && hooksWithTests.length > 0) {
     const wantTests = await p.confirm({
       message: `Install unit tests for ${plural(hooksWithTests.length, 'hook')} into ${pc.cyan('tests/hooks/')}? ${pc.dim('(vitest — helps SonarQube gating)')}`,
       initialValue: true,
@@ -276,7 +304,7 @@ async function directInstall(slugs, args) {
   const log = { warn: m => console.warn(`  ! ${m}`) }
   const result = doInstall(hooks, dirs, args.scope, log)
   console.log(`  ✓ ${dirs.settingsPath}`)
-  if (args.withTests && args.scope !== 'global') {
+  if (args.withTests && !isGlobalScope(args.scope)) {
     try {
       const testResult = doInstallTests(hooks, process.cwd(), { mkdirSync, writeFileSync, join: pathJoin })
       if (testResult.testCount > 0)
@@ -289,8 +317,9 @@ async function directInstall(slugs, args) {
   if (hints.length > 0) {
     for (const h of hints) console.warn(`  ⚠  ${h.slug}: ${h.hint}`)
   }
+  const agent = dirs.format === 'codex' ? 'Codex' : 'Claude Code'
   console.log(`\n✅ ${plural(result.hookCount, 'hook')} installed · star us → ${REPO_URL}`)
-  console.log('   Restart Claude Code to activate.\n')
+  console.log(`   Restart ${agent} to activate.\n`)
 }
 
 const HELP = `
@@ -304,7 +333,10 @@ const HELP = `
     --hooks <slugs>   Comma-separated list of hook slugs (omit for default set)
     --global, -g      Install into ~/.claude instead of ./.claude
     --copilot         Install into ./.claude with paths adapted for GitHub Copilot
-    --scope <s>       "project" (default), "global", or "copilot"
+    --codex-project   Install into ./.codex/hooks.json (OpenAI Codex, this repo)
+    --codex-profile   Install into ~/.codex/hooks.json (OpenAI Codex, all projects)
+    --scope <s>       "project" (default), "global", "copilot",
+                      "codex-project", or "codex-profile"
     --with-tests      Also install vitest unit tests into tests/hooks/ (project scope only)
     --yes, -y         Skip prompts (non-interactive install)
     --version, -v     Show version

package/bin/core.mjs

@@ -13,6 +13,19 @@ const BLOCKING_EVENTS = new Set([
 
 // Matches $CLAUDE_PROJECT_DIR and ${CLAUDE_PROJECT_DIR}.
 export const PROJECT_DIR_RE = /\$\{?CLAUDE_PROJECT_DIR\}?/g
+// Matches the "$CLAUDE_PROJECT_DIR/.claude/" prefix — rewritten to ".codex/" for
+// Codex installs so scripts resolve under the Codex agent directory instead.
+const CLAUDE_PREFIX_RE = /\$\{?CLAUDE_PROJECT_DIR\}?\/\.claude\//g
+
+// All recognized install scopes. Claude-family: project, global, copilot
+// (settings.json under .claude). Codex-family: codex-project, codex-profile
+// (hooks.json under .codex, events at the top level).
+export const SCOPES = new Set(['project', 'global', 'copilot', 'codex-project', 'codex-profile'])
+const GLOBAL_SCOPES = new Set(['global', 'codex-profile'])
+const CODEX_SCOPES = new Set(['codex-project', 'codex-profile'])
+
+export const isGlobalScope = scope => GLOBAL_SCOPES.has(scope)
+export const isCodexScope = scope => CODEX_SCOPES.has(scope)
 
 function splitList(raw) {
   return raw.split(',').map(s => s.trim()).filter(Boolean)
@@ -39,9 +52,11 @@ export function parseArgs(argv) {
     if (arg === '--global' || arg === '-g') { result.scope = 'global'; continue }
     if (arg === '--project') { result.scope = 'project'; continue }
     if (arg === '--copilot') { result.scope = 'copilot'; continue }
+    if (arg === '--codex-profile') { result.scope = 'codex-profile'; continue }
+    if (arg === '--codex-project') { result.scope = 'codex-project'; continue }
     if (arg.startsWith('--scope=')) {
       const v = arg.slice('--scope='.length)
-      if (v === 'global' || v === 'project') result.scope = v
+      if (SCOPES.has(v)) result.scope = v
       continue
     }
     if (arg.startsWith('--hooks=')) { result.hooks = splitList(arg.slice('--hooks='.length)); continue }
@@ -52,16 +67,22 @@ export function parseArgs(argv) {
   return result
 }
 
-// Resolves where .claude/ lives for a given scope. Project → cwd; global → home.
+// Resolves where the agent directory lives for a given scope.
+// Project/copilot → cwd; global/codex-profile → home.
+// Claude-family uses .claude/settings.json; Codex-family uses .codex/hooks.json.
+// `claudeDir`/`settingsPath` keys are kept for back-compat (they hold the agent
+// dir and config-file path regardless of which agent it targets).
 export function resolveScopeRoot(scope, { cwd, home }) {
-  const root = scope === 'global' ? home : cwd
-  const claudeDir = join(root, '.claude')
+  const root = isGlobalScope(scope) ? home : cwd
+  const codex = isCodexScope(scope)
+  const agentDir = join(root, codex ? '.codex' : '.claude')
   return {
     scope,
     root,
-    claudeDir,
-    hooksDir: join(claudeDir, 'hooks'),
-    settingsPath: join(claudeDir, 'settings.json'),
+    format: codex ? 'codex' : 'claude',
+    claudeDir: agentDir,
+    hooksDir: join(agentDir, 'hooks'),
+    settingsPath: join(agentDir, codex ? 'hooks.json' : 'settings.json'),
   }
 }
 
@@ -99,10 +120,27 @@ export function mergeHooks(existing, incoming) {
   return merged
 }
 
+// Rewrites a hook command's path for the target scope:
+// - global             → $CLAUDE_PROJECT_DIR ↦ absolute global root (.claude stays)
+// - copilot            → strips $CLAUDE_PROJECT_DIR/ (relative, Copilot compatible)
+// - codex-project      → "$CLAUDE_PROJECT_DIR/.claude/" ↦ ".codex/" (relative)
+// - codex-profile      → "$CLAUDE_PROJECT_DIR/.claude/" ↦ "<home>/.codex/" (absolute)
+function rewriteCommand(command, scope, globalRoot) {
+  if (scope === 'global' && globalRoot)
+    return command.replace(PROJECT_DIR_RE, globalRoot)
+  if (scope === 'copilot')
+    return command.replace(/\$\{?CLAUDE_PROJECT_DIR\}?\//g, '')
+  if (scope === 'codex-project')
+    return command.replace(CLAUDE_PREFIX_RE, '.codex/')
+  if (scope === 'codex-profile' && globalRoot)
+    return command.replace(CLAUDE_PREFIX_RE, `${globalRoot}/.codex/`)
+  return command
+}
+
 // Gathers the hook fragments from an API hook list into a single event→entries
-// map. For global scope, rewrites $CLAUDE_PROJECT_DIR to the absolute global
-// root so commands resolve outside any project. For copilot scope, strips
-// $CLAUDE_PROJECT_DIR/ so paths become relative (GitHub Copilot compatible).
+// map, rewriting command paths per scope (see rewriteCommand). The resulting map
+// is identical in shape for both Claude (settings.hooks) and Codex (top-level
+// hooks.json) — only doInstall decides how to nest it on disk.
 export function collectIncomingHooks(hooks, { scope = 'project', globalRoot } = {}) {
   const incoming = {}
   for (const hook of hooks) {
@@ -115,11 +153,7 @@ export function collectIncomingHooks(hooks, { scope = 'project', globalRoot } =
           ...entry,
           hooks: entry.hooks.map(h => {
             if (!h.command || typeof h.command !== 'string') return h
-            if (scope === 'global' && globalRoot)
-              return { ...h, command: h.command.replace(PROJECT_DIR_RE, globalRoot) }
-            if (scope === 'copilot')
-              return { ...h, command: h.command.replace(/\$\{?CLAUDE_PROJECT_DIR\}?\//g, '') }
-            return h
+            return { ...h, command: rewriteCommand(h.command, scope, globalRoot) }
           }),
         })
       }
@@ -128,6 +162,13 @@ export function collectIncomingHooks(hooks, { scope = 'project', globalRoot } =
   return incoming
 }
 
+// Maps a hook's script_path to its on-disk destination for the target scope.
+// Codex installs relocate scripts from .claude/hooks/ to .codex/hooks/.
+export function resolveScriptPath(scriptPath, scope) {
+  if (isCodexScope(scope)) return scriptPath.replace(/^\.claude\//, '.codex/')
+  return scriptPath
+}
+
 export function isBlockingEvent(event) {
   return BLOCKING_EVENTS.has(event)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookstack-cli",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "description": "CLI installer for the Hookstack catalogue of Claude Code hooks",
   "type": "module",
   "bin": {