What causes "--codex cannot be combined with --hook-only" in rtk-ai/rtk?

Remove --hook-only: `rtk init --codex` (Codex mode already handles hook setup its own way)

--codex cannot be combined with --hook-only

Error message

--codex cannot be combined with --hook-only

What it means

rtk's `rtk init` rejects the combination of --codex and --hook-only. Codex mode runs its own dedicated setup path (run_codex_mode), which already implies a hook-only style configuration, so an explicit --hook-only request is contradictory. The bail fires before any filesystem changes are made.

Solutions

Remove --hook-only: `rtk init --codex` (Codex mode already handles hook setup its own way)
Remove --codex and keep plain hook-only init: `rtk init --hook-only`

Example fix

// before
rtk init --codex --hook-only
// after
rtk init --codex

Defensive patterns

Strategy: validation

Validate before calling

const codex = args.includes("--codex");
const hookOnly = args.includes("--hook-only");
if (codex && hookOnly) throw new Error("--codex cannot be combined with --hook-only");

Prevention

Remember --codex already implies its own hook setup; never pair it with --hook-only
Keep agent selection (--codex) and installation style (--hook-only) in separate script variables and only use one at a time

When it happens

Trigger: Running `rtk init --codex --hook-only`. Fires whenever the parsed `codex` flag is true and `hook_only` is true, after the --claude-md conflict check inside the `codex` branch of HooksInit::run.

Common situations: A user who normally runs `rtk init --hook-only` adds --codex to switch agents, assuming the two flags compose. Automation scripts that always append --hook-only regardless of agent selection.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of rtk-ai/rtk@0924356b4c (2026-09-19). Data as JSON: /api/errors/57904733f57518f5. Report an issue: GitHub.

Appendix: source

Thrown at src/hooks/init.rs:404

    install_windsurf: bool,
    install_cline: bool,
    claude_md: bool,
    hook_only: bool,
    codex: bool,
    patch_mode: PatchMode,
    ctx: InitContext,
) -> Result<()> {
    let InitContext { dry_run, .. } = ctx;
    // Validation: Codex mode conflicts
    if codex {
        if install_opencode {
            anyhow::bail!("--codex cannot be combined with --opencode");
        }
        if claude_md {
            anyhow::bail!("--codex cannot be combined with --claude-md");
        }
        if hook_only {
            anyhow::bail!("--codex cannot be combined with --hook-only");
        }
        if matches!(patch_mode, PatchMode::Auto) {
            anyhow::bail!("--codex cannot be combined with --auto-patch");
        }
        if matches!(patch_mode, PatchMode::Skip) {
            anyhow::bail!("--codex cannot be combined with --no-patch");
        }
        run_codex_mode(global, ctx)?;
    } else {
        // Validation: Global-only features
        if install_opencode && !global {
            anyhow::bail!("OpenCode plugin is global-only. Use: rtk init -g --opencode");
        }

        if install_cursor && !global {
            anyhow::bail!("Cursor hooks are global-only. Use: rtk init -g --agent cursor");
        }

View on GitHub (pinned to 0924356b4c)