Add Cursor plugin compatibility and install docs#467
Conversation
Enable native Cursor plugin discovery with a .cursor-plugin manifest, and make the SessionStart hook emit both Cursor and Claude response shapes so context injection works across both platforms. Document Cursor install usage in the README while keeping Claude-first wording. Co-authored-by: Cursor <cursoragent@cursor.com>
📝 WalkthroughWalkthroughThe pull request adds plugin configuration for Cursor integration, updates documentation with IDE-specific installation instructions, and refactors the session startup hook to externalize context variables for better maintainability. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
hooks/session-start.sh (1)
18-18:⚠️ Potential issue | 🟡 Minor
2>&1causes cat's stderr to leak into the content on failure.If
catfails (e.g., file missing),2>&1redirects the error message to stdout, which gets captured in the variable. Then||fires and theechooutput is also captured. The result is both messages concatenated. Drop the2>&1so only the fallback echo is captured on failure:Proposed fix
-using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill") +using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>/dev/null || echo "Error reading using-superpowers skill")🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@hooks/session-start.sh` at line 18, The variable using_superpowers_content is capturing both cat's stdout and stderr because of the "2>&1" redirection, causing error messages to be concatenated with the fallback; remove the "2>&1" from the cat invocation so only cat's stdout is captured and the || echo fallback runs alone (i.e., call cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" without 2>&1 so using_superpowers_content only gets the file contents or the fallback message).
🧹 Nitpick comments (1)
README.md (1)
56-56: Verification guidance could mention what "success" looks like.The existing Claude-only text was similarly vague, but now that two platforms are covered, it may help users to know a concrete indicator — e.g., seeing the
<EXTREMELY_IMPORTANT>context block or the "You have superpowers" message in the session output.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 56, The README's instruction "Start a new session..." is missing concrete verification guidance; update that paragraph to tell users what success looks like by naming specific indicators to check for (e.g., the presence of the "<EXTREMELY_IMPORTANT>" context block or the "You have superpowers" message in the session output) and include examples for both Claude and Cursor so users can confirm the skill invoked correctly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.cursor-plugin/plugin.json:
- Line 5: The plugin version is hardcoded in .cursor-plugin/plugin.json
("version": "4.3.0") which causes drift across multiple plugin.json files;
refactor to source the version from a single location (e.g., VERSION file or
build config) and update the project build/release script to inject or generate
the "version" field into .cursor-plugin/plugin.json and
.claude-plugin/plugin.json at release time; locate the "version" key in both
plugin.json files and replace hardcoded values with the injection point (or
generation step) so both files are always produced from the single source of
truth.
- Around line 14-17: Update the manifest keys "skills", "agents", "commands",
and "hooks" so their paths point to the repository root instead of the manifest
directory; replace the current "./skills/", "./agents/", "./commands/", and
"./hooks/hooks.json" values with "../skills/", "../agents/", "../commands/", and
"../hooks/hooks.json" respectively so Cursor resolves them to the correct
root-level directories.
In `@README.md`:
- Around line 46-52: Remove the incorrect "/plugin-add superpowers" command from
the "Cursor (via Plugin Marketplace)" section and replace it with the real
installation instructions: explain the CLI method (tell users to install the
"code" shell command via Command Palette → Install "code" to shell and then run
code --install-extension publisher.extension) and the GUI method (Command
Palette → Extensions: Install from VSIX… and select the .vsix file); ensure the
section header "Cursor (via Plugin Marketplace)" remains and the text clearly
states Cursor does not support "/plugin-add" syntax.
---
Outside diff comments:
In `@hooks/session-start.sh`:
- Line 18: The variable using_superpowers_content is capturing both cat's stdout
and stderr because of the "2>&1" redirection, causing error messages to be
concatenated with the fallback; remove the "2>&1" from the cat invocation so
only cat's stdout is captured and the || echo fallback runs alone (i.e., call
cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" without 2>&1 so
using_superpowers_content only gets the file contents or the fallback message).
---
Nitpick comments:
In `@README.md`:
- Line 56: The README's instruction "Start a new session..." is missing concrete
verification guidance; update that paragraph to tell users what success looks
like by naming specific indicators to check for (e.g., the presence of the
"<EXTREMELY_IMPORTANT>" context block or the "You have superpowers" message in
the session output) and include examples for both Claude and Cursor so users can
confirm the skill invoked correctly.
| "name": "superpowers", | ||
| "displayName": "Superpowers", | ||
| "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques", | ||
| "version": "4.3.0", |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if there's a version defined elsewhere in the project
rg -n '"version"' --type json | head -20
rg -n 'version' package.json Cargo.toml pyproject.toml setup.py 2>/dev/null | head -10Repository: obra/superpowers
Length of output: 42
🏁 Script executed:
#!/bin/bash
# List the root directory to understand project structure
echo "=== Root directory structure ==="
ls -la | head -20
echo -e "\n=== Search for version in all files ==="
rg -i "version" -l | head -20
echo -e "\n=== Check for common version config files ==="
find . -maxdepth 2 -type f \( -name "package.json" -o -name "*.toml" -o -name "setup.py" -o -name "version.txt" -o -name "_version.py" \) 2>/dev/null
echo -e "\n=== Content of plugin.json ==="
cat -n ".cursor-plugin/plugin.json" 2>/dev/nullRepository: obra/superpowers
Length of output: 2667
🏁 Script executed:
#!/bin/bash
echo "=== All plugin.json files and their versions ==="
find . -name "plugin.json" -type f | while read f; do
echo -e "\n--- $f ---"
cat -n "$f" | grep -i version
done
echo -e "\n=== Recent entries in RELEASE-NOTES.md ==="
head -50 RELEASE-NOTES.mdRepository: obra/superpowers
Length of output: 3299
🏁 Script executed:
#!/bin/bash
echo "=== All plugin directories ==="
find . -maxdepth 2 -type d -name ".*-plugin" -o -name ".opencode"
echo -e "\n=== All plugin.json files ==="
find . -name "plugin.json" -type f
echo -e "\n=== Search for release/version scripts ==="
find . -maxdepth 2 -type f \( -name "*release*" -o -name "*version*" \) ! -path "./.git/*"
echo -e "\n=== Check for GitHub workflows ==="
find .github -type f 2>/dev/null
echo -e "\n=== Search for version update instructions in README ==="
rg -A5 -B5 "version|release" README.md 2>/dev/null | head -40Repository: obra/superpowers
Length of output: 1568
Multiple plugin.json files require manual version synchronization.
The "version": "4.3.0" is hardcoded in both .cursor-plugin/plugin.json and .claude-plugin/plugin.json. With multiple plugin files requiring the same version, there's no automated mechanism to keep them in sync during releases. Consider creating a single source of truth for the version (e.g., a version.txt or build script) that all plugin.json files reference or are generated from during the release process.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor-plugin/plugin.json at line 5, The plugin version is hardcoded in
.cursor-plugin/plugin.json ("version": "4.3.0") which causes drift across
multiple plugin.json files; refactor to source the version from a single
location (e.g., VERSION file or build config) and update the project
build/release script to inject or generate the "version" field into
.cursor-plugin/plugin.json and .claude-plugin/plugin.json at release time;
locate the "version" key in both plugin.json files and replace hardcoded values
with the injection point (or generation step) so both files are always produced
from the single source of truth.
| "skills": "./skills/", | ||
| "agents": "./agents/", | ||
| "commands": "./commands/", | ||
| "hooks": "./hooks/hooks.json" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if these directories exist at the repo root vs inside .cursor-plugin/
echo "=== Repo root ==="
ls -d skills/ agents/ commands/ hooks/ 2>&1 | head -20
echo ""
echo "=== Inside .cursor-plugin/ ==="
ls -d .cursor-plugin/skills/ .cursor-plugin/agents/ .cursor-plugin/commands/ .cursor-plugin/hooks/ 2>&1
echo ""
echo "=== Check .cursor-plugin structure ==="
ls -la .cursor-plugin/ 2>&1Repository: obra/superpowers
Length of output: 635
🌐 Web query:
Cursor plugin manifest path resolution relative paths behavior
💡 Result:
Cursor extensions use the VS Code extension model, so “manifest” paths behave like VS Code’s package.json contribution paths:
- Paths are interpreted as files inside the extension, i.e., relative to the extension root (the folder containing
package.json). VS Code examples use./…for this (e.g.,contributes.iconThemes[].path, andiconDefinitions[].iconPath). [1] - For some fields (notably
contributes.jsonValidation[].url), VS Code uses a special rule: if the value starts with./(or.) it’s treated as a local file shipped with the extension; if it doesn’t (e.g., starts with/schemas/...), it’s treated like a remote URL to fetch, which fails for “local” files. [2]
Practical rule: when you mean “a file in my extension”, prefer ./path/to/file rather than /path/to/file. [1][2]
Fix relative paths—they incorrectly reference .cursor-plugin/ subdirectories instead of the repo root.
The manifest at .cursor-plugin/plugin.json uses paths like ./skills/, ./agents/, etc., which Cursor (following VS Code's extension model) resolves relative to the manifest's directory (.cursor-plugin/). These directories don't exist there. The actual directories are at the repo root. Update paths to: ../skills/, ../agents/, ../commands/, ../hooks/hooks.json.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor-plugin/plugin.json around lines 14 - 17, Update the manifest keys
"skills", "agents", "commands", and "hooks" so their paths point to the
repository root instead of the manifest directory; replace the current
"./skills/", "./agents/", "./commands/", and "./hooks/hooks.json" values with
"../skills/", "../agents/", "../commands/", and "../hooks/hooks.json"
respectively so Cursor resolves them to the correct root-level directories.
| ### Cursor (via Plugin Marketplace) | ||
|
|
||
| In Cursor Agent chat, install from marketplace: | ||
|
|
||
| ```text | ||
| /plugin-add superpowers | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Cursor IDE plugin-add command syntax install plugin
💡 Result:
Cursor “plugin add” / install-plugin command
Cursor doesn’t use a plugin-add command. It installs VS Code extensions.
Install an extension from the command line (recommended)
- In Cursor, install the
code(VS Code-compatible) shell command: Command Palette → Install “code” to shell (Cursor also offers Install “cursor” to shell). [1] - Then run:
code --install-extension publisher.extension
# or install from a VSIX file:
code --install-extension /path/to/extension.vsixThe CLI also supports @version (e.g., publisher.extension@1.2.3). [2]
Install a VSIX from inside Cursor (GUI)
Command Palette → Extensions: Install from VSIX… and pick the .vsix file. [3]
Sources: [1] [2] [3]
Remove the incorrect /plugin-add superpowers command from the Cursor installation section.
Cursor does not support /plugin-add syntax. Cursor installs VS Code extensions using the code CLI command or the GUI. The correct installation methods are:
- CLI (recommended): Install the
codeshell command via Command Palette → Install "code" to shell, then runcode --install-extension publisher.extension - GUI: Command Palette → Extensions: Install from VSIX… and select the
.vsixfile
Update the README to reflect the actual Cursor installation process instead of the non-existent /plugin-add command.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 46 - 52, Remove the incorrect "/plugin-add
superpowers" command from the "Cursor (via Plugin Marketplace)" section and
replace it with the real installation instructions: explain the CLI method (tell
users to install the "code" shell command via Command Palette → Install "code"
to shell and then run code --install-extension publisher.extension) and the GUI
method (Command Palette → Extensions: Install from VSIX… and select the .vsix
file); ensure the section header "Cursor (via Plugin Marketplace)" remains and
the text clearly states Cursor does not support "/plugin-add" syntax.
|
LGTM thanks! |
2 participants
Summary
.cursor-plugin/plugin.jsonmanifest so Superpowers is discoverable as a Cursor plugin without changing existing Claude packaginghooks/session-start.shto emit both Cursor (additional_context) and Claude (hookSpecificOutput.additionalContext) response shapes for cross-platform hook compatibilityREADME.mdwith Claude-first wording in shared guidanceTest plan
bash hooks/session-start.shand assert output JSON contains bothadditional_contextandhookSpecificOutput.additionalContext.cursor-plugin/plugin.jsonwithpython3JSON load to verify manifest validityMade with Cursor
Summary by CodeRabbit
New Features
Documentation