{"record":{"id":"07bbfb90669b29e5","repo":"rtk-ai/rtk","slug":"cursor-hooks-are-global-only-use-rtk-init-g-a","errorCode":null,"errorMessage":"Cursor hooks are global-only. Use: rtk init -g --agent cursor","messagePattern":"Cursor hooks are global-only\\. Use: rtk init -g --agent cursor","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/hooks/init.rs","lineNumber":302,"sourceCode":"        }\n        if hook_only {\n            anyhow::bail!(\"--codex cannot be combined with --hook-only\");\n        }\n        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                }","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/rtk-ai/rtk/blob/d977e1c31621fe8704e6500ceeb9c7a0de2b6836/src/hooks/init.rs#L284-L320","documentation":"Cursor hooks are installed at the user level (global Cursor settings), not per-project, so rtk init requires the global flag. The validation at src/hooks/init.rs:302 bails when install_cursor is set and global is false, embedding the corrective command `rtk init -g --agent cursor` in the message.","triggerScenarios":"`rtk init --agent cursor` without -g/--global — typically run inside a project directory right after cloning, expecting a repo-local hook install like the default Claude Code mode.","commonSituations":"New-machine setup following Cursor docs while cd'd into a repo; porting a project-local init script to Cursor by only swapping the agent flag; assuming symmetry between local Claude Code hooks and Cursor hooks.","solutions":["Run `rtk init -g --agent cursor` as the error instructs","For project-local setup, use the default: `rtk init` (Claude Code mode writes into the project)","Windsurf has the same rule (`rtk init -g --agent windsurf`) — batch your global-only setups with one -g run"],"exampleFix":"# before\nrtk init --agent cursor\n# Cursor hooks are global-only. Use: rtk init -g --agent cursor\n\n# after\nrtk init -g --agent cursor\n# combine other global-only agents in the same global run if needed:\nrtk init -g --agent windsurf","handlingStrategy":"validation","validationCode":"bash:\n# Cursor hooks install user-level: require -g up front\nif [[ \"$*\" == *--agent\\ cursor* && \"$*\" != *-g* && \"$*\" != *--global* ]]; then\n  echo \"Cursor hooks are global-only — rerunning with -g\" >&2\n  set -- -g \"$@\"\nfi\nrtk init \"$@\"","typeGuard":"rust:\nfn cursor_invocation_valid(cursor: bool, global: bool) -> bool {\n    !cursor || global\n}","tryCatchPattern":"bash:\nrtk init --agent cursor 2>err.txt || {\n  grep -q 'global-only' err.txt && exec rtk init -g --agent cursor\n}","preventionTips":["Cursor (and windsurf, opencode) hooks are user-level — always `rtk init -g --agent cursor`","For repo-local setup use default `rtk init`, which writes into the project","Don't assume flag symmetry across agent targets; check init --help per agent"],"tags":["init","cursor","global","usage","hooks"],"backgroundTag":null,"analyzedSha":"d977e1c31621fe8704e6500ceeb9c7a0de2b6836","analyzedAt":"2026-08-16T05:40:46.291Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}