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

Unable to resolve OMX launcher path for tmux HUD bootstrap

Error message

Unable to resolve OMX launcher path for tmux HUD bootstrap

What it means

Identical family to the exec variant: before performing the tmux HUD bootstrap, the launcher must resolve its own CLI entry path to re-exec OMX inside the tmux pane. If resolveOmxCliEntryPath cannot find the entry from argv[1]/cwd/env, the bootstrap is aborted.

Source

Thrown at src/cli/index.ts:6304

  launchPolicy: CodexLaunchPolicy = "direct",
  detachedPreflight?: DetachedPreflightAvailable,
  projectLocalCodexHomeForCleanup?: string,
  runtimeCodexHomeForCleanup?: string,
  runtimeContext?: MadmaxWorktreeRuntimeContext,
  verifiedMadmaxContext?: VerifiedMadmaxDetachedContext,
  launchControlPlane?: DetachedLaunchControlPlane,
): Promise<{ postLaunchHandledExternally: boolean }> {
  void preLaunchOptions;
  const launchArgs = injectModelInstructionsBypassArgs(
    cwd,
    args,
    process.env,
    sessionModelInstructionsPath(cwd, sessionId),
  );
  const nativeWindows = isNativeWindows();
  const omxBin = resolveOmxCliEntryPath({ argv1: process.argv[1], cwd, env: process.env });
  if (!omxBin) {
    throw new Error("Unable to resolve OMX launcher path for tmux HUD bootstrap");
  }
  const runtimeEnvOverlay = buildMadmaxWorktreeRuntimeEnvOverlay(runtimeContext);
  let verifiedTeamContext: VerifiedDetachedTeamContext | undefined;
  if (launchPolicy === "detached-tmux") {
    try {
      verifiedTeamContext = await resolveVerifiedDetachedTeamContext(cwd, process.env);
    } catch {
      verifiedTeamContext = undefined;
    }
  }
  const verifiedMadmaxContextForLaunch = verifiedMadmaxContext ?? (
    runtimeContext?.madmaxDetachedContext
      ? {
          root: runtimeContext.omxRoot,
          sourceCwd: runtimeContext.sourceCwd,
          context: runtimeContext.madmaxDetachedContext,
          runsRoot: resolveMadmaxRunsRoot(process.env),
        }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Reinstall OMX via the supported installer so the bin shim and entry file match
2. Invoke through the omx binary rather than wrappers/loaders that obscure argv[1]
3. Verify the install: run `which omx` and confirm the target file exists; `npm rebuild`/reinstall if not
4. If embedding OMX, ensure the child launch env/cwd allow entry resolution (consult resolveOmxCliEntryPath's expected inputs)

Example fix

# before
$ npx --cache /tmp omx hud

# after
$ npm i -g omx && omx hud

const bin = resolveOmxCliEntryPath({ argv1: process.argv[1], cwd, env: process.env });
if (!bin) { console.error("OMX entry unresolvable; run `npm i -g omx` and use the omx bin"); process.exit(1); }

try { await startHud(); } catch (e) { if (e instanceof Error && /tmux HUD bootstrap/.test(e.message)) { /* reinstall omx and retry via bin */ } throw e; }

When it happens

Trigger: Starting a HUD/detached-tmux session where argv[1] does not point to a resolvable OMX entry file — broken installs, odd package-manager shims (pnpm, npx cache), wrappers or loaders that rewrite argv, or running the bundled CLI through a custom runtime.

Common situations: Global installs whose bin symlink points to a moved file; running via npx with a cache miss mid-install; containerized or bundled deployments; invoking the CLI's internals from a test harness.

Related errors

• Unable to resolve OMX launcher path for exec
• invalid auth slot path
• auth directory must not be a symlink: ${dir}
• auth path is not a directory: ${dir}
• ${label} is not a file: ${path}

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