Yeachan-Heo/oh-my-codex · error · Error

Unknown hooks subcommand: ${subcommand}

Error message

Unknown hooks subcommand: ${subcommand}

What it means

The `hooks` CLI command dispatches on its first positional argument against a fixed subcommand list (including `init`, `validate`, `help`). An unrecognized subcommand falls through the switch and throws this error.

Source

Thrown at src/cli/hooks.ts:86

    case 'init':
      await initHooks();
      return;
    case 'status':
      await statusHooks();
      return;
    case 'validate':
      await validateHooks();
      return;
    case 'test':
      await testHooks();
      return;
    case 'help':
    case '--help':
    case '-h':
      console.log(HELP);
      return;
    default:
      throw new Error(`Unknown hooks subcommand: ${subcommand}`);
  }
}

async function initHooks(): Promise<void> {
  const cwd = process.cwd();
  const dir = hooksDir(cwd);
  const samplePath = samplePluginPath(cwd);
  await mkdir(dir, { recursive: true });

  if (existsSync(samplePath)) {
    console.log(`hooks scaffold already exists: ${samplePath}`);
    return;
  }

  await writeFile(samplePath, SAMPLE_PLUGIN);
  console.log(`Created ${samplePath}`);
  console.log('Plugins are enabled by default. Disable with OMX_HOOK_PLUGINS=0.');
}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Run `omx hooks help` to list supported subcommands
2. Correct the subcommand spelling
3. Check the changelog if you expected the subcommand to exist

Example fix

# before
omx hooks instal

# after
omx hooks init

const KNOWN_HOOKS = new Set(['init', 'validate', 'help', '--help', '-h']); // sync with hooks.ts switch
const sub = args[0];
if (!sub || !KNOWN_HOOKS.has(sub)) {
  console.error(`Unknown hooks subcommand. Valid: init, validate, help`);
  process.exit(1);
}

function isHooksSubcommand(s: string | undefined): s is 'init' | 'validate' | 'help' {
  return !!s && ['init', 'validate', 'help'].includes(s);
}

try {
  await hooksCommand(args);
} catch (e) {
  if ((e as Error).message.startsWith('Unknown hooks subcommand')) { /* print HELP text */ }
  else throw e;
}

When it happens

Trigger: Running `omx hooks <unknown>` where the first arg matches no case (e.g. `omx hooks instal`, or a subcommand removed/renamed in this version).

Common situations: Typos, aliases from other tools (e.g. `hooks add`), or version drift where a subcommand no longer exists.

Related errors

• --keep-policy must be one of: score_improvement, pass_only
• Unknown capabilities subcommand: ${parsed.subcommand}
• Unknown capabilities option: ${arg}
• ${flag} requires a value
• hooks validation failed (${failed} plugin${failed === 1 ? ''

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/0ed868e4bd92191b. Report an issue: GitHub.