rtk-ai/rtk · error

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

Error message

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

What it means

`rtk init --codex` is an exclusive mode; the validation block at src/hooks/init.rs:283 rejects --claude-md alongside it because --codex does not write a CLAUDE.md (it installs Codex config instead), so the two request incompatible outputs.

Source

Thrown at src/hooks/init.rs:283

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

Solutions

  1. Run `rtk init --codex` alone for the Codex setup
  2. Get the CLAUDE.md from a separate default run: `rtk init` (or `rtk init --claude-md` without --codex)
  3. Review `rtk init --help` for which flags compose with which modes

Example fix

# before
rtk init --codex --claude-md
# --codex cannot be combined with --claude-md

# after: split into two runs
rtk init --codex
rtk init --claude-md
Defensive patterns

Strategy: validation

Validate before calling

bash:
if [[ "$*" == *--codex* && "$*" == *--claude-md* ]]; then
  echo "--codex and --claude-md are mutually exclusive; run them separately" >&2
  exit 2
fi
rtk init "$@"

Type guard

rust:
fn codex_claude_md_conflict(codex: bool, claude_md: bool) -> bool {
    codex && claude_md
}

Try / catch

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

Prevention

When it happens

Trigger: `rtk init --codex --claude-md`. Both flags parse, but codex mode would never write CLAUDE.md, so init fails fast rather than half-perform.

Common situations: Users wanting rules files for BOTH Codex and Claude concatenating flags from docs; setup scripts evolving over time by appending options; --codex mistaken for 'also install for Codex'.

Related errors

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