# Session Bootstrap & Hook System

> Understanding the automatic activation layer that triggers skills at the start of every session, ensuring the agent is immediately oriented to the project's methodology.

- 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

- `hooks/session-start`
- `hooks/hooks.json`
- `hooks/run-hook.cmd`
- `hooks/hooks-cursor.json`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [hooks/session-start](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start)
- [hooks/hooks.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks.json)
- [hooks/run-hook.cmd](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/run-hook.cmd)
- [hooks/hooks-cursor.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks-cursor.json)
- [skills/using-superpowers/SKILL.md](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/skills/using-superpowers/SKILL.md)
- [docs/windows/polyglot-hooks.md](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/docs/windows/polyglot-hooks.md)
</details>

# Session Bootstrap & Hook System

The Session Bootstrap system is the automatic activation layer that ensures an agent is immediately oriented to the Superpowers methodology at the start of every session. By injecting core instructions and the `using-superpowers` skill into the agent's initial context, the system transforms a generic coding assistant into a disciplined, process-driven engineer before the first line of code is ever discussed.

This system is designed to be platform-agnostic and cross-platform, supporting various agent harnesses (Claude Code, Cursor, Copilot CLI) across Windows, macOS, and Linux. It eliminates the need for manual setup by the user, making "Superpowers" a persistent, zero-configuration upgrade to the development environment.

## Automatic Activation Layer

The bootstrap process is triggered by platform-specific `SessionStart` hooks. These hooks are registered in configuration files that the respective agent harnesses monitor.

| Platform | Configuration File | Trigger Event |
| :--- | :--- | :--- |
| **Claude Code** | [hooks/hooks.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks.json) | `startup`, `clear`, or `compact` |
| **Cursor** | [hooks/hooks-cursor.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks-cursor.json) | `sessionStart` |

When these events occur, the harness executes the registered command, which points to the Superpowers hook runner.

Sources: [hooks/hooks.json:3-14](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks.json#L3-L14), [hooks/hooks-cursor.json:3-9](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks-cursor.json#L3-L9)

## Cross-Platform Polyglot Runner

To ensure compatibility across operating systems, Superpowers utilizes a **polyglot wrapper** technique. Since Windows CMD cannot execute `.sh` files directly and may not have `bash` in the `PATH`, the `run-hook.cmd` script acts as a dual-language entry point.

### The Reusable Wrapper Pattern
The `run-hook.cmd` file is valid syntax in both Windows CMD (batch) and Unix shells (bash).

- **On Windows**: CMD sees the initial `: << 'CMDBLOCK'` as a label and ignores the rest of the line. It then executes the batch portion to find and invoke `bash.exe` (typically from Git for Windows).
- **On Unix**: Bash sees `:` as a no-op and `<< 'CMDBLOCK'` as the start of a heredoc, effectively skipping the Windows-specific batch commands and executing the Unix-specific logic at the end.

```cmd
: << 'CMDBLOCK'
@echo off
REM Windows logic to find bash.exe and run the script
...
exit /b 0
CMDBLOCK

# Unix logic to run the script directly
exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
```

Sources: [hooks/run-hook.cmd:1-46](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/run-hook.cmd#L1-L46), [docs/windows/polyglot-hooks.md:18-51](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/docs/windows/polyglot-hooks.md#L18-L51)

## Session Start Logic & Context Injection

The core bootstrap logic resides in the `hooks/session-start` bash script. Its primary responsibility is to construct a JSON object containing the injected context that the agent harness will merge into the session.

### Execution Steps
1. **Environment Detection**: Determines the plugin root directory and detects the current platform (Cursor vs. Claude Code vs. others) via environment variables like `CURSOR_PLUGIN_ROOT` or `CLAUDE_PLUGIN_ROOT`.
2. **Legacy Migration Check**: Checks for the existence of `~/.config/superpowers/skills` and prepares a warning message if found, ensuring users migrate to the modern Claude Code skills directory.
3. **Introduction Injection**: Reads the full content of the `superpowers:using-superpowers` skill. This skill establishes the non-negotiable rule: **Invoke relevant skills BEFORE any response or action**.
4. **JSON Serialization**: Escapes the skill content and warning messages for safe embedding into a JSON response. The script uses high-performance bash parameter substitution for escaping.

Sources: [hooks/session-start:6-35](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start#L6-L35)

## Platform-Specific Integration

Different harnesses expect injected context in different JSON structures. The `session-start` script dynamically adapts its output to match the host platform's requirements.

| Platform | Detection Variable | Output JSON Key |
| :--- | :--- | :--- |
| **Cursor** | `CURSOR_PLUGIN_ROOT` | `additional_context` |
| **Claude Code** | `CLAUDE_PLUGIN_ROOT` | `hookSpecificOutput.additionalContext` |
| **Copilot CLI** | `COPILOT_CLI` | `additionalContext` |

This precise mapping ensures that the orientation instructions are correctly interpreted by the agent, regardless of the IDE or CLI tool being used.

Sources: [hooks/session-start:46-55](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start#L46-L55)

## Summary

The Session Bootstrap & Hook System is the "silent partner" of Superpowers, providing the infrastructure necessary for autonomous, disciplined agent behavior. By leveraging cross-platform polyglot scripts and targeted context injection, it ensures that every session begins with the agent fully aware of its "Superpowers" and the rigorous workflows required to use them effectively.

Sources: [hooks/session-start:35-55](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start#L35-L55)