This document covers the Claude Code platform-specific integration for Superpowers, including marketplace installation, hooks system, bootstrap injection, and native skill tool integration. For general multi-platform architecture, see 4.3. For skill discovery mechanisms common across platforms, see 4.5.
Claude Code integration uses a plugin manifest system with marketplace-based installation. The integration centers on a synchronous SessionStart hook that injects the using-superpowers skill content as bootstrap context before the agent's first turn, ensuring mandatory skill-checking protocol is established from session initialization.
Key components:
.claude-plugin/plugin.json.claude-plugin/marketplace.jsonhooks/hooks.jsonhooks/session-start.shskills/commands/agents/The plugin is defined in .claude-plugin/plugin.json1-13 with metadata and versioning:
Claude Code automatically detects and loads:
skills/ directory containing skill definitionscommands/ directory for slash commandsagents/ directory for subagent configurationshooks/hooks.json for session lifecycle hooksSources: .claude-plugin/plugin.json1-13
The marketplace configuration at .claude-plugin/marketplace.json1-20 defines plugin metadata and source location. Users install via two-step process:
Sources: .claude-plugin/marketplace.json1-20 README.md32-44
Claude Code requires a hooks.json file to register lifecycle hooks. As of v4.3.0, the SessionStart hook runs synchronously (async: false) to ensure bootstrap context is injected before the agent's first response:
Critical change in v4.3.0: Changed from async: true to async: false to prevent race condition where hook could fail to complete before model's first turn, leaving using-superpowers instructions out of context.
Sources: RELEASE-NOTES.md25-27
Sources: hooks/session-start.sh1-51 RELEASE-NOTES.md25-27
The hook script hooks/session-start.sh1-51 performs critical bootstrap injection:
Path resolution:
Uses ${BASH_SOURCE[0]:-$0} fallback for execution contexts where BASH_SOURCE is unbound.
Legacy detection:
Detects pre-v3.0 skills directory structure and builds migration warning.
Content injection:
Reads the foundational using-superpowers skill content directly.
JSON escaping optimization:
Uses bash parameter substitution (${s//old/new}) instead of character-by-character loop. Each replacement is a single C-level pass, resulting in 7x speedup on macOS and dramatic improvement on Windows Git Bash (from 60+ seconds to under 10).
Output structure:
Dual shape provides compatibility with both Claude Code (expects hookSpecificOutput.additionalContext) and Cursor (expects additional_context).
Sources: hooks/session-start.sh1-51 RELEASE-NOTES.md51-53
The injected context establishes foundational behavior before the agent's first turn:
This prevents the agent from needing to invoke using-superpowers manually - it's already in context as bootstrap, creating a "prime directive" for skill-checking behavior.
Sources: hooks/session-start.sh35-36 RELEASE-NOTES.md336-337
Claude Code provides a native Skill tool for discovering and invoking skills. The tool:
Skills are invoked using namespaced syntax superpowers:skill-name or short form if unambiguous.
Sources: RELEASE-NOTES.md179-183
Claude Code implements a three-tier priority system for skill resolution:
| Priority | Location | Purpose |
|---|---|---|
| 1 (Highest) | Project .claude/skills/ | Project-specific overrides |
| 2 | Personal ~/.claude/skills/ | User customizations |
| 3 (Lowest) | Plugin skills/ | Superpowers defaults |
Higher-priority skills with matching names shadow lower-priority ones, enabling progressive customization without forking the plugin.
Sources: RELEASE-NOTES.md311-312
Claude Code supports slash commands defined in commands/ directory. Superpowers provides three commands that redirect to corresponding skills:
| Command | Target Skill | Purpose |
|---|---|---|
/brainstorm | superpowers:brainstorming | Design phase workflow |
/write-plan | superpowers:writing-plans | Implementation plan creation |
/execute-plan | superpowers:executing-plans | Batch execution with checkpoints |
Key configuration: As of v4.0.2, all commands have disable-model-invocation: true, restricting them to manual user invocation only. The agent cannot invoke these commands via the Skill tool, preventing confusion since they just redirect to skills anyway.
Commands serve as convenient aliases for frequently-used skills but are not required - agents primarily invoke skills autonomously based on task recognition.
Sources: RELEASE-NOTES.md167-172
The plugin includes a pre-configured agent at agents/code-reviewer.md1-48 for systematic code review workflows:
The agent provides structured review against:
Skills reference the agent using namespaced syntax superpowers:code-reviewer in two-stage review workflows.
Sources: agents/code-reviewer.md1-48 RELEASE-NOTES.md424-434
Claude Code 2.1.x changed hook execution on Windows, requiring fixes:
Problem: Claude Code 2.1.x auto-detects .sh files and prepends bash, breaking polyglot wrappers. Command bash "run-hook.cmd" session-start.sh tried to execute .cmd as bash script.
Solution: Call session-start.sh directly in hooks.json. Claude Code handles bash invocation automatically.
Line endings: Added .gitattributes to enforce LF line endings for shell scripts, preventing CRLF issues on Windows checkout.
Sources: RELEASE-NOTES.md41-46 RELEASE-NOTES.md137-141
v4.2.0 introduced async hook execution to prevent terminal freeze on Windows where synchronous hook blocked TUI raw mode, freezing keyboard input.
v4.3.0 reverted to synchronous after discovering async execution created race condition - hook could fail to complete before agent's first turn, leaving bootstrap context missing.
Trade-off: Windows users may experience brief terminal delay during hook execution, but guaranteed bootstrap injection is critical for system functionality.
Sources: RELEASE-NOTES.md47-49 RELEASE-NOTES.md25-27
SessionStart hook synchronous: Changed async: false to ensure bootstrap completes before first agent turn.
Brainstorming hard gates: Skill now enforces workflow with <HARD-GATE> markers, mandatory checklist, and graphviz process flow to prevent skipping design phase.
EnterPlanMode intercept: using-superpowers workflow graph intercepts Claude's native plan mode, routing through brainstorming skill instead.
Sources: RELEASE-NOTES.md3-22
v4.0.2: Commands restricted to user-only invocation (disable-model-invocation: true).
v4.0.1: Clarified Skill tool usage - tool loads content directly, no separate Read needed.
v4.0.0: Two-stage code review in subagent workflows (spec compliance → code quality).
Sources: RELEASE-NOTES.md167-217
v3.6.2: Linux compatibility fix for polyglot hook wrapper.
v3.5.1: OpenCode bootstrap refactor (separate platform, see 5.2).
v3.2.2: Strengthened using-superpowers with mandatory protocol and rationalization counters.
Sources: RELEASE-NOTES.md279-418
Claude Code integration includes comprehensive test suite at tests/claude-code/:
claude -p for headless executionanalyze-token-usage.py tracks subagent costsSee 9.1 for detailed test suite documentation.
Sources: RELEASE-NOTES.md238-246
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.