This page describes how the superpowers plugin hooks into each supported AI coding platform at a technical level: what files are involved, how context is injected, and what mechanism each platform uses for skill discovery. For the per-platform installation steps, see pages 2.1, 2.2, 2.3, and 2.4. For detail on what the bootstrap content contains and how it is constructed, see 4.4. For how skills are located on disk after bootstrap, see 4.5.
Superpowers targets four platforms, each with a different plugin API. The table below summarizes how each integration works end-to-end.
| Platform | Registration | Context Injection Hook | Skill Discovery | Config Location |
|---|---|---|---|---|
| Claude Code | .claude-plugin/plugin.json | SessionStart via hooks.json | Claude Code Skill tool | .claude-plugin/ |
| Cursor | .cursor-plugin/plugin.json | SessionStart via hooks.json + additionalContext | Cursor skill tool | .cursor-plugin/ |
| OpenCode | Symlink .opencode/plugins/superpowers.js | experimental.chat.system.transform | OpenCode native skill tool | .opencode/ |
| Codex | Symlink ~/.agents/skills/superpowers | None (native discovery) | Native ~/.agents/skills/ scan | .codex/ |
Sources: .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 docs/README.opencode.md240-256 RELEASE-NOTES.md53-59
Integration entry points by platform:
Sources: .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 RELEASE-NOTES.md6-10 RELEASE-NOTES.md53-59 docs/README.opencode.md260-266
Claude Code uses a plugin manifest at .claude-plugin/plugin.json to register the plugin. The manifest contains metadata (name, version, author) but does not declare hooks or skill directories—those are handled separately by hooks/hooks.json.
Hook execution chain:
hooks/hooks.json on startup.SessionStart, it calls run-hook.cmd session-start.run-hook.cmd is a polyglot file: on Windows it routes to bash via discovered Git for Windows paths; on Unix it execs bash directly.session-start (extensionless bash script) reads skills/using-superpowers/SKILL.md, constructs a JSON payload, and writes it to stdout.The JSON output schema uses two fields for compatibility:
The additional_context top-level field was added in v4.3.1 for Cursor compatibility; Claude Code uses hookSpecificOutput.additionalContext.
Key files:
| File | Role |
|---|---|
.claude-plugin/plugin.json | Plugin registration manifest |
hooks/hooks.json | Declares SessionStart trigger and command |
hooks/run-hook.cmd | Polyglot wrapper (Windows CMD + Unix bash in one file) |
hooks/session-start | Bash script; produces JSON bootstrap output |
Sources: .claude-plugin/plugin.json1-13 RELEASE-NOTES.md12-23 RELEASE-NOTES.md45-49
Cursor uses a separate manifest at .cursor-plugin/plugin.json. Unlike the Claude Code manifest, the Cursor manifest declares all plugin assets explicitly:
.cursor-plugin/plugin.json1-18
The skills, agents, and commands fields tell Cursor where to find plugin assets. The hooks field points to the same hooks/hooks.json used by Claude Code, so the same SessionStart script runs on both platforms.
The critical difference is the hook output format. When Cursor processes the SessionStart output, it reads the additional_context top-level field (added in v4.3.1) rather than hookSpecificOutput.additionalContext. Both fields are present in the output so both platforms work from the same script.
Sources: .cursor-plugin/plugin.json1-18 RELEASE-NOTES.md6-10
OpenCode does not have a plugin marketplace. Integration requires:
~/.config/opencode/superpowers.opencode/plugins/superpowers.js into ~/.config/opencode/plugins/skills/ into ~/.config/opencode/skills/superpowersPlugin hook mechanism:
The file .opencode/plugins/superpowers.js registers a experimental.chat.system.transform hook. This hook is called before each model request and injects the bootstrap content (the using-superpowers skill body plus tool mapping instructions) directly into the system prompt. This avoids the session reset side effect that occurred with the older session.prompt({ noReply: true }) approach.
Skill discovery:
OpenCode has a native skill tool. By symlinking the skills/ directory into ~/.config/opencode/skills/superpowers, all superpowers skills appear under the superpowers/ namespace in OpenCode's native skill tool—no custom discovery code is needed.
Tool mapping:
Skills in the repository are written for Claude Code's tool names. The bootstrap content injected by superpowers.js includes a mapping table so the agent adapts automatically:
| Claude Code Tool | OpenCode Equivalent |
|---|---|
TodoWrite | update_plan |
Task (subagent) | @mention syntax |
Skill | Native skill tool |
| File operations | Native OpenCode tools |
Sources: docs/README.opencode.md240-256 .opencode/INSTALL.md1-38 RELEASE-NOTES.md139-153 RELEASE-NOTES.md313-319
Codex uses native skill discovery from ~/.agents/skills/. No custom plugin code runs—the agent's runtime scans that directory for skill files at startup.
Setup:
~/.codex/superpowers/ ← git clone of obra/superpowers
~/.agents/skills/superpowers ← symlink → ~/.codex/superpowers/skills/
The symlink causes Codex to discover all superpowers skills under the superpowers namespace without any plugin code.
Activation conditions:
Codex activates a skill when any of the following match:
name field matches the user's requestdescription field matches the user's intentusing-superpowers meta-skill directs the agent to load a specific skillBecause there is no SessionStart hook, the using-superpowers skill is not pre-loaded into context. Instead, Codex discovers it via the native scan and loads it when triggered.
History note: Prior to v4.2.0, Codex used a superpowers-codex Node.js CLI with use_skill and find_skills subcommands. This was replaced by the symlink approach to eliminate the Node.js dependency.
Sources: RELEASE-NOTES.md53-59 RELEASE-NOTES.md75-82
The file lib/skills-core.js is an ES module shared between the OpenCode plugin and the Codex integration. It provides:
| Function | Purpose |
|---|---|
extractFrontmatter(filePath) | Parses YAML frontmatter from a SKILL.md file |
findSkillsInDir(dir, sourceType, maxDepth) | Recursively scans a directory for SKILL.md files |
resolveSkillPath(skillName, superpowersDir, personalDir) | Resolves a skill name to a file path, respecting the superpowers: prefix escape hatch |
checkForUpdates(repoDir) | Runs git fetch with a 3-second timeout to detect upstream changes |
stripFrontmatter(content) | Returns skill body without the YAML header |
Sources: lib/skills-core.js1-208
How resolveSkillPath handles platform priority:
Sources: lib/skills-core.js108-140
The following diagram shows the data flow from plugin files to agent context for each platform.
Context injection paths by platform:
Sources: RELEASE-NOTES.md45-49 RELEASE-NOTES.md139-153 docs/README.opencode.md240-246 RELEASE-NOTES.md53-59
The following diagram maps each platform's integration to the specific files in the repository.
Sources: .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 .opencode/INSTALL.md22-33 RELEASE-NOTES.md53-59 lib/skills-core.js1-10
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.