slopus/happy · error

Codex CLI is not installed Please install Codex CLI using o

Error message

Codex CLI is not installed

Please install Codex CLI using one of these methods:

Option 1 - npm (recommended):
  npm install -g @openai/codex

Option 2 - Homebrew (macOS):
  brew install --cask codex

Alternatively, use Claude Code:
  happy claude

What it means

CodexAppServerClient.connect() refuses to start when the Codex CLI app-server binary cannot be located on the machine (isAppServerAvailable() is false). The happy CLI shells out to the Codex CLI to run Codex sessions, so without the binary there is nothing to connect to. The message includes concrete install instructions and points to `happy claude` as the Claude Code alternative.

Source

Thrown at packages/happy-cli/src/codex/codexAppServerClient.ts:599

                    this.extractTurnId(params),
                    'completed',
                    null,
                    `${method}:final_answer`,
                );
            }
            return true;
        }

        return method.startsWith('item/');
    }

    // ─── Lifecycle ──────────────────────────────────────────────

    async connect(): Promise<void> {
        if (this.connected) return;

        if (!isAppServerAvailable()) {
            throw new Error(
                'Codex CLI is not installed\n\n' +
                'Please install Codex CLI using one of these methods:\n\n' +
                'Option 1 - npm (recommended):\n  npm install -g @openai/codex\n\n' +
                'Option 2 - Homebrew (macOS):\n  brew install --cask codex\n\n' +
                'Alternatively, use Claude Code:\n  happy claude',
            );
        }

        let command = 'codex';
        let args = ['app-server', '--listen', 'stdio://'];
        this.sandboxEnabled = false;

        if (this.sandboxConfig?.enabled && process.platform !== 'win32') {
            try {
                this.sandboxCleanup = await initializeSandbox(this.sandboxConfig, process.cwd());
                const wrapped = await wrapForMcpTransport('codex', ['app-server', '--listen', 'stdio://']);
                command = wrapped.command;
                args = wrapped.args;

View on GitHub (pinned to b824cd0a46)

Solutions

1. Install Codex CLI: npm install -g @openai/codex (or brew install --cask codex on macOS)
2. Verify the binary is on PATH: `which codex` / `codex --version`
3. If already installed, fix PATH so the install prefix (e.g. npm global bin) is included
4. Use Claude Code instead: run `happy claude`

Example fix

// before
happy codex  // fails: Codex CLI is not installed

// after
$ npm install -g @openai/codex
$ happy codex

import { execFileSync } from 'node:child_process';
function isCodexCliAvailable(): boolean {
  try { execFileSync('codex', ['--version'], { stdio: 'ignore' }); return true; }
  catch { return false; }
}
if (!isCodexCliAvailable()) {
  console.error('Install Codex CLI: npm install -g @openai/codex');
  process.exit(1);
}

try {
  await client.connect();
} catch (error) {
  if ((error as Error).message.includes('Codex CLI is not installed')) {
    console.error('Run `npm install -g @openai/codex` or use `happy claude`.');
  } else { throw error; }
}

When it happens

Trigger: Any code path that creates a CodexAppServerClient and calls connect() (directly or via withCodexAppServerClient, reconnect, reconnectAndResumeThread) on a machine where the Codex CLI is not installed or not on PATH.

Common situations: Fresh dev machines or CI containers without `@openai/codex` installed; Codex installed under a non-PATH location; switching from Claude-only usage to `happy codex`; broken Homebrew cask after an OS upgrade.

Related errors

• Usage: happy acp <agent-name> or happy acp -- <command> [arg
• Missing command after "--". Usage: happy acp -- <command> [a
• The chosen rewind point is no longer present in the source C
• Daemon-spawned sessions cannot use local/interactive mode. U
• No thread available to resume.

AI-assisted analysis of slopus/happy@b824cd0a46 (2026-08-31). Data as JSON: /api/errors/d7642da9b6fb4d0b. Report an issue: GitHub.