hook-runner

Modular hook runner for Claude Code. Workflows group related modules into enforceable pipelines. Enable a workflow and its modules activate together.

Quick Start

npx grobomo/hook-runner --yes    # install + enable default workflows
node setup.js --uninstall --confirm  # clean removal, restore original settings

Workflows

/hook-runner workflow              # list available workflows
node setup.js --workflow enable shtd --global
node setup.js --workflow audit     # coverage report
node setup.js --workflow query Edit  # which workflows affect Edit?

Built-in: shtd (spec→test→implement→PR), messaging-safety, no-local-docker, cross-project-reset.

Module Contract

// WORKFLOW: shtd
// WHY: Explain the real incident that caused this module.
module.exports = function(input) {
  if (shouldBlock) return { decision: "block", reason: "WHY blocked" };
  return null; // pass
};

• Return null to pass, {decision: "block"} to block
• Sync or async (4s timeout for async)
• // WORKFLOW: name restricts to that workflow
• // requires: mod1 for dependencies

CLI

node setup.js                     # setup wizard
node setup.js --yes               # non-interactive + default workflows
node setup.js --report [--open]   # HTML report
node setup.js --health            # verify installation
node setup.js --list              # catalog vs installed
node setup.js --sync              # sync from GitHub
node setup.js --stats             # hook activity summary
node setup.js --perf              # timing analysis
node setup.js --workflow <cmd>    # workflow management
node setup.js --test              # run all tests
node setup.js --uninstall --confirm  # restore original settings