# Cross-Harness Installation & Adapters

> How to integrate Superpowers into your preferred environment, including Claude Code, Codex, Gemini, Cursor, and OpenCode, using native plugin mechanisms.

- Repository: obra/superpowers
- GitHub: https://github.com/obra/superpowers
- Human wiki: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85
- Complete Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/llms-full.txt

## Source Files

- `README.md`
- `gemini-extension.json`
- `.claude-plugin/plugin.json`
- `.cursor-plugin/plugin.json`
- `.codex-plugin/plugin.json`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [gemini-extension.json](gemini-extension.json)
- [.claude-plugin/plugin.json](.claude-plugin/plugin.json)
- [.cursor-plugin/plugin.json](.cursor-plugin/plugin.json)
- [.codex-plugin/plugin.json](.codex-plugin/plugin.json)
- [.opencode/plugins/superpowers.js](.opencode/plugins/superpowers.js)
- [hooks/session-start](hooks/session-start)
- [.opencode/INSTALL.md](.opencode/INSTALL.md)
</details>

# Cross-Harness Installation & Adapters

Superpowers is designed as a portable agentic skills framework that integrates natively with a wide variety of AI coding harnesses. Whether you are using Claude Code, Cursor, Gemini, or OpenCode, Superpowers provides a consistent experience by adapting its delivery mechanism to the native plugin or extension architecture of each environment.

This page details the installation procedures for supported harnesses and explains the underlying adapter logic that ensures the `using-superpowers` bootstrap is correctly injected into your agent sessions.

## Installation by Harness

Installation differs by harness. If you use multiple environments, you must install Superpowers separately for each one to ensure the appropriate native hooks are registered.

| Harness | Installation Command / Method |
| :--- | :--- |
| **Claude Code** | `/plugin install superpowers@claude-plugins-official` |
| **Cursor** | `/add-plugin superpowers` (in Agent chat) |
| **Gemini CLI** | `gemini extensions install https://github.com/obra/superpowers` |
| **Codex CLI** | `/plugins` -> search for `superpowers` -> `Install Plugin` |
| **OpenCode** | Add `superpowers@git+...` to `plugin` array in `opencode.json` |
| **Factory Droid** | `droid plugin install superpowers@superpowers` |
| **Copilot CLI** | `copilot plugin install superpowers@superpowers-marketplace` |

Sources: [README.md:35-153](), [.opencode/INSTALL.md:12-20]()

## Adapters & Session Injection

Superpowers uses a "bootstrap" mechanism to ensure the agent is aware of its capabilities as soon as a session starts. This is implemented via native hooks that inject the `using-superpowers` skill content into the initial conversation context.

### The SessionStart Hook

For most harnesses (Claude Code, Cursor, Codex), the integration relies on a `SessionStart` hook defined in the plugin manifest. This hook executes a script that detects the platform and formats the context injection according to the expected JSON schema.

```bash
# hooks/session-start snippet
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
  # Cursor sets CURSOR_PLUGIN_ROOT
  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
  # Claude Code sets CLAUDE_PLUGIN_ROOT
  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
fi
```
Sources: [hooks/session-start:46-55](), [.cursor-plugin/plugin.json:10-20]()

### OpenCode Adapter Logic

OpenCode uses a more specialized adapter implemented in Javascript. It utilizes the `experimental.chat.messages.transform` hook to inject the bootstrap into the first user message of every session. This approach avoids token bloat from repeated system messages while ensuring the agent always sees the instructions.

```javascript
// .opencode/plugins/superpowers.js
'experimental.chat.messages.transform': async (_input, output) => {
  const bootstrap = getBootstrapContent();
  if (!bootstrap || !output.messages.length) return;
  const firstUser = output.messages.find(m => m.info.role === 'user');
  if (!firstUser || !firstUser.parts.length) return;

  // Guard: skip if already injected
  if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;

  const ref = firstUser.parts[0];
  firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
}
```
Sources: [.opencode/plugins/superpowers.js:120-133]()

### Injection Sequence

The following diagram illustrates how Superpowers injects context across different platforms:

```mermaid
sequenceDiagram
    participant User
    participant Harness as Harness (Claude/Cursor/OpenCode)
    participant Plugin as Superpowers Plugin
    participant Skills as Skills Library

    User->>Harness: Starts Session
    Harness->>Plugin: Triggers SessionStart/Transform Hook
    Plugin->>Skills: Reads using-superpowers/SKILL.md
    Skills-->>Plugin: Returns bootstrap content
    Plugin-->>Harness: Returns formatted injection JSON
    Harness->>User: Agent starts with Superpowers awareness
```

## Tool Mapping for OpenCode

Because OpenCode has a different native toolset than Claude Code, the Superpowers adapter automatically maps skill-referenced tools to their OpenCode equivalents during bootstrap injection.

- `TodoWrite` is mapped to the native `todowrite` tool.
- `Task` tool subagent requests are translated to OpenCode's `@mention` syntax.
- `Skill` tool calls are redirected to OpenCode's native `skill` tool.

Sources: [.opencode/plugins/superpowers.js:76-83]()

## Summary

Superpowers maintains portability by abstracting harness-specific details into dedicated adapters and hooks. By leveraging native plugin mechanisms like Claude Code's `SessionStart` and OpenCode's message transformation hooks, Superpowers ensures that its core software development methodology is available consistently across all major AI coding platforms. For the latest installation updates and specific version pinning, refer to the [README.md:103-153]() and platform-specific manifests like [gemini-extension.json:1-7]().