rtk-ai/rtk · error

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

Error message

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

What it means

`rtk init --codex` is an exclusive mode that performs its own complete installation; the validation at src/hooks/init.rs:286 rejects --hook-only alongside it. --hook-only means 'install only hooks, skip other setup', which has no meaning inside codex mode's single-purpose flow.

Source

Thrown at src/hooks/init.rs:286

    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 d977e1c316)

Solutions

  1. Run `rtk init --codex` alone — codex mode is already a scoped, minimal install
  2. If you wanted hook-only for Claude Code, drop --codex: `rtk init --hook-only`
  3. Check `rtk init --help` before combining rarely-used flags

Example fix

# before
rtk init --codex --hook-only
# --codex cannot be combined with --hook-only

# after
rtk init --codex        # codex mode is already scoped
rtk init --hook-only    # separate concern, separate run
Defensive patterns

Strategy: validation

Validate before calling

bash:
if [[ "$*" == *--codex* && "$*" == *--hook-only* ]]; then
  echo "--codex and --hook-only are mutually exclusive" >&2
  exit 2
fi
rtk init "$@"

Type guard

rust:
fn codex_hook_only_conflict(codex: bool, hook_only: bool) -> bool {
    codex && hook_only
}

Try / catch

rust:
// clap-level: #[arg(long, conflicts_with = "hook_only")] codex: bool,
if let Err(e) = init::run(...) {
    if e.to_string().contains("--codex cannot be combined with --hook-only") { exit(2); }
}

Prevention

When it happens

Trigger: `rtk init --codex --hook-only`. The pair parses at the clap level and fails only in init's validation, with --codex named as the offending mode.

Common situations: Copying a minimal-install invocation (`rtk init --hook-only`) and appending --codex; scripts trying to keep the footprint small while adding Codex; misunderstanding codex mode as composable.

Related errors

AI-assisted analysis of rtk-ai/rtk@d977e1c316 (2026-08-16). Data as JSON: /api/errors/57904733f57518f5. Report an issue: GitHub.