This page documents Cursor-specific integration for the Superpowers plugin system. It covers the .cursor-plugin/ manifest structure, the hooks-cursor.json configuration, tool compatibility, and the cross-platform hook execution logic. For general platform integration concepts, see 4.3 Multi-Platform Integration. For session lifecycle mechanics, see 4.4 Session Lifecycle and Bootstrap.
Cursor support provides a native plugin integration that allows Cursor's AI agent to utilize the Superpowers skill library. Unlike OpenCode or Codex, which may require manual configuration, Cursor uses a structured plugin manifest and a specific hook format.
The integration handles Cursor-specific environmental variables and camelCase hook formats. Cursor executes the session-start hook to inject the using-superpowers meta-skill context into the conversation history.
Sources: .cursor-plugin/plugin.json1-23 hooks/hooks-cursor.json1-11 hooks/session-start38-40
The Cursor plugin manifest defines plugin metadata and identifies the location of resources like skills and hooks.
Title: Cursor Plugin Resource Mapping
Sources: .cursor-plugin/plugin.json1-23
| Field | Value | Purpose |
|---|---|---|
name | "superpowers" | Internal plugin identifier [.cursor-plugin/plugin.json2] |
displayName | "Superpowers" | UI name in Cursor [.cursor-plugin/plugin.json3] |
version | "6.1.1" | Plugin version [.cursor-plugin/plugin.json5] |
skills | "./skills/" | Path to the directory containing SKILL.md files [.cursor-plugin/plugin.json21] |
hooks | "./hooks/hooks-cursor.json" | Pointer to the Cursor-specific hook manifest [.cursor-plugin/plugin.json22] |
Sources: .cursor-plugin/plugin.json1-23
Cursor utilizes a specific JSON format for hooks that differs from Claude Code. It uses camelCase for event names (e.g., sessionStart) and requires a version field.
Title: Cursor Hook Manifest Schema
Sources: hooks/hooks-cursor.json1-11
When a session begins, Cursor triggers the sessionStart hook. This executes the hooks/run-hook.cmd wrapper with the session-start argument. The script performs platform detection to ensure the output format matches what Cursor expects.
Title: Cursor Session Initialization Flow
Sources: hooks/session-start1-49 hooks/hooks-cursor.json4-8
The session-start script uses environment variables to determine if it is running within Cursor. If CURSOR_PLUGIN_ROOT is set, it emits a JSON object where the context is placed in the additional_context field.
| Platform | Detected Variable | JSON Output Field |
|---|---|---|
| Cursor | CURSOR_PLUGIN_ROOT | additional_context [hooks/session-start38-40] |
| Claude Code | CLAUDE_PLUGIN_ROOT | hookSpecificOutput.additionalContext [hooks/session-start41-43] |
| Other / Copilot | COPILOT_CLI or fallback | additionalContext [hooks/session-start44-47] |
Sources: hooks/session-start38-47
The session-start hook includes a robust escape_for_json function to ensure that skill content (which often contains quotes, backslashes, and newlines) can be safely embedded in the JSON response sent back to Cursor.
Sources: hooks/session-start16-24
Cursor specifically requires the additional_context key at the top level of the JSON response. The script uses printf instead of heredocs to avoid a known bash 5.3+ hang issue.
Sources: hooks/session-start36-40
Users install the integration by adding the Superpowers repository as a plugin in Cursor.
.cursor-plugin/plugin.json [.cursor-plugin/plugin.json1-23].sessionStart hook defined in hooks-cursor.json runs [hooks/hooks-cursor.json4-8].session-start script reads the using-superpowers skill and injects it as additional_context to guide the AI's behavior [hooks/session-start10-40].Sources: .cursor-plugin/plugin.json22 hooks/hooks-cursor.json4-8 hooks/session-start38-40
Refresh this wiki