What causes "--codex cannot be combined with --claude-md" in rtk-ai/rtk?

Run two separate init commands: `rtk init --codex` and `rtk init --claude-md`

--codex cannot be combined with --claude-md

Error message

--codex cannot be combined with --claude-md

What it means

rtk's `rtk init` command refuses to initialize Codex mode together with the --claude-md flag. Codex mode configures the Codex agent exclusively, so Claude-specific setup (installing a CLAUDE.md integration) is meaningless alongside it. The check lives at the top of HooksInit::run before any files are written, so it fails fast with no side effects.

Solutions

Run two separate init commands: `rtk init --codex` and `rtk init --claude-md`
Drop --claude-md if only Codex integration is wanted: `rtk init --codex`
Drop --codex if only the Claude integration is wanted

Example fix

// before
rtk init --codex --claude-md
// after
rtk init --codex
rtk init --claude-md

Defensive patterns

Strategy: validation

Validate before calling

const codex = args.includes("--codex");
const claudeMd = args.includes("--claude-md");
if (codex && claudeMd) throw new Error("--codex cannot be combined with --claude-md");

Prevention

Pick one agent integration per rtk init invocation
Build init commands from an agent variable, not by concatenating multiple agent flags
Check `rtk init --help` for documented flag conflicts before scripting

When it happens

Trigger: Running `rtk init --codex --claude-md` (with or without -g). The bail fires whenever the parsed `codex` flag is true and `claude_md` is true, immediately after the --opencode conflict check.

Common situations: A developer wants hooks for both Codex and Claude and passes both flags in one command, or copies an init command from docs for Claude and appends --codex to also target Codex. Scripts templating multiple agent flags into a single init call.

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/2a3c1ab431ff19cf. Report an issue: GitHub.

Appendix: source

Thrown at src/hooks/init.rs:401

    install_claude: bool,
    install_opencode: bool,
    install_cursor: bool,
    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 {

View on GitHub (pinned to 0924356b4c)