{"record":{"id":"0872be38ac6f819d","repo":"rtk-ai/rtk","slug":"windsurf-support-is-global-only-use-rtk-init-g","errorCode":null,"errorMessage":"Windsurf support is global-only. Use: rtk init -g --agent windsurf","messagePattern":"Windsurf support is global-only\\. Use: rtk init -g --agent windsurf","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/hooks/init.rs","lineNumber":306,"sourceCode":"        if matches!(patch_mode, PatchMode::Auto) {\n            anyhow::bail!(\"--codex cannot be combined with --auto-patch\");\n        }\n        if matches!(patch_mode, PatchMode::Skip) {\n            anyhow::bail!(\"--codex cannot be combined with --no-patch\");\n        }\n        run_codex_mode(global, ctx)?;\n    } else {\n        // Validation: Global-only features\n        if install_opencode && !global {\n            anyhow::bail!(\"OpenCode plugin is global-only. Use: rtk init -g --opencode\");\n        }\n\n        if install_cursor && !global {\n            anyhow::bail!(\"Cursor hooks are global-only. Use: rtk init -g --agent cursor\");\n        }\n\n        if install_windsurf && !global {\n            anyhow::bail!(\"Windsurf support is global-only. Use: rtk init -g --agent windsurf\");\n        }\n\n        if install_windsurf {\n            run_windsurf_mode(ctx)?;\n        } else if install_cline {\n            run_cline_mode(ctx)?;\n        } else {\n            // Mode selection (Claude Code / OpenCode)\n            match (install_claude, install_opencode, claude_md, hook_only) {\n                (false, true, _, _) => run_opencode_only_mode(ctx)?,\n                (true, opencode, true, _) => run_claude_md_mode(global, opencode, ctx)?,\n                (true, opencode, false, true) => {\n                    run_hook_only_mode(global, patch_mode, opencode, ctx)?\n                }\n                (true, opencode, false, false) => {\n                    run_default_mode(global, patch_mode, opencode, ctx)?\n                }\n                (false, false, _, _) => {","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/rtk-ai/rtk/blob/d977e1c31621fe8704e6500ceeb9c7a0de2b6836/src/hooks/init.rs#L288-L324","documentation":"rtk installs Windsurf support only by editing the user's global Windsurf config, so run_init rejects a project-scoped install before touching any file. The bail embeds the corrected command. Nothing has been written when this error appears, so re-running with -g is safe.","triggerScenarios":"Running `rtk init --agent windsurf` (or any flag combination that sets install_windsurf) without `--global`/`-g` — the check at src/hooks/init.rs:308.","commonSituations":"Copying a project-scoped `rtk init` line used for Claude Code and swapping the agent name; wrapper scripts that deliberately never pass -g (CI sandboxes, shared machines, dotfile repos).","solutions":["Run `rtk init -g --agent windsurf`","If global writes are forbidden in your environment, use a project-scoped agent instead (plain `rtk init` for Claude Code)","Check each agent's scope in `rtk init --help` before scripting init"],"exampleFix":"# before\nrtk init --agent windsurf   # error: global-only\n\n# after\nrtk init -g --agent windsurf","handlingStrategy":"validation","validationCode":"# bash: pair global-only agents with -g before invoking rtk\ncase \"$AGENT\" in windsurf|cursor|opencode|gemini|vibe) GLOBAL_FLAG='-g';; esac\nrtk init $GLOBAL_FLAG --agent \"$AGENT\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Memorize the split: windsurf/cursor/opencode/gemini/vibe are global-only (-g); kilocode/antigravity/kimi are project-only (no -g)","Wrap rtk init in a script that whitelists (agent, scope) pairs and fails fast on mismatches","Use --dry-run first: `rtk init -g --agent windsurf --dry-run` shows every write without the flag error risk"],"tags":["cli","init","windsurf","agent-scoping","validation"],"backgroundTag":null,"analyzedSha":"d977e1c31621fe8704e6500ceeb9c7a0de2b6836","analyzedAt":"2026-08-16T05:40:46.291Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}