Yeachan-Heo/oh-my-codex · warning

[omx] warning: failed to launch hook-derived watcher

Error message

[omx] warning: failed to launch hook-derived watcher

What it means

launchBackgroundHelper failed when spawning the hook-derived watcher script (e.g. ENOENT for node or the script, EACCES). The watcher is skipped; hook-driven notifications will not fire.

Source

Thrown at src/cli/index.ts:7863

  await mkdir(join(omxRoot(cwd), "state"), { recursive: true }).catch(
    (error: unknown) => {
      console.warn(
        "[omx] warning: failed to create hook-derived watcher state directory",
        {
          cwd,
          error: error instanceof Error ? error.message : String(error),
        },
      );
    },
  );
  let watcherPid: number | undefined;
  try {
    watcherPid = await launchBackgroundHelper([watcherScript, "--cwd", cwd], {
      cwd,
      env: process.env,
    });
  } catch (error: unknown) {
    console.warn("[omx] warning: failed to launch hook-derived watcher", {
      cwd,
      error: error instanceof Error ? error.message : String(error),
    });
    return;
  }

  if (!watcherPid) return;

  await writeFile(
    pidPath,
    JSON.stringify(
      { pid: watcherPid, started_at: new Date().toISOString() },
      null,
      2,
    ),
  ).catch((error: unknown) => {
    console.warn(
      "[omx] warning: failed to write hook-derived watcher pid file",

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Reinstall the package to restore helper scripts
2. chmod +x the watcher script
3. Ensure PATH includes the node runtime used to spawn helpers

Example fix

// before
chmod -x node_modules/omx/dist/hooks/watcher.js

# after
chmod +x node_modules/omx/dist/hooks/watcher.js

import { existsSync } from 'node:fs';
import { which } from './which';
function hookWatcherLaunchable(script: string): boolean {
  return which('node') !== null && existsSync(script);
}

When it happens

Trigger: Spawning [watcherScript, '--cwd', cwd] with env: process.env fails because the script path does not exist or is not executable, or the interpreter cannot be found.

Common situations: Corrupted/partial package install; PATH stripped in the child environment; script not executable after archive extraction; macOS Gatekeeper or SELinux blocking exec.

Related errors

• [omx] warning: failed to launch notify fallback watcher
• [omx] warning: failed to stop stale hook-derived watcher
• [omx] warning: failed to create hook-derived watcher state d
• [omx] warning: failed to write hook-derived watcher pid file
• [omx] warning: failed to stop hook-derived watcher process

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