This page covers installation of Superpowers in OpenAI Codex CLI. Because Codex does not have a plugin marketplace, setup is performed manually via git clone and a filesystem symlink. For plugin-marketplace-based installation on Claude Code, see 2.1. For OpenCode manual setup, see 2.3.
Codex CLI performs native skill discovery: it scans ~/.agents/skills/ at startup and loads any skill libraries found there. Superpowers exposes its skills through a symlink that points into a cloned copy of the repository.
Codex Skill Discovery — File System Layout
Sources: README.md54-62 section 5.3 of table of contents
The fastest way to install is to instruct Codex to fetch and execute the canonical install document:
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
Codex will retrieve .codex/INSTALL.md and perform the steps described below on your behalf.
Sources: README.md56-59
Clone Superpowers into the Codex configuration directory:
This places the full repository at ~/.codex/superpowers/, including the skills/ subdirectory.
Ensure the Codex native skill discovery directory exists:
Link the Superpowers skills directory into the Codex skill discovery path:
After this step, Codex will find all Superpowers skills at ~/.agents/skills/superpowers/.
Close and reopen Codex CLI. Native skill discovery runs at startup; no reload command is available.
On Windows, ln -s is not available. Use mklink /J (directory junction) instead:
| Platform | Command | Type |
|---|---|---|
| macOS / Linux | ln -s <target> <link> | Symbolic link |
| Windows (CMD, elevated) | mklink /J <link> <target> | Directory junction |
Note that the argument order differs between ln -s and mklink /J: ln takes target then link; mklink takes link then target.
Post-Installation Paths
Sources: README.md54-62 section 5.3, section 4.1 of table of contents
Codex activates a skill when any of the following conditions is met:
| Condition | Description |
|---|---|
| Name match | The task or prompt directly references the skill's name field from its YAML frontmatter |
| Description match | The task content matches trigger phrases in the skill's description field |
using-superpowers direction | The meta-skill using-superpowers instructs the agent to check for applicable skills before any action |
The using-superpowers skill acts as the bootstrap entry point: once loaded, it mandates that the agent check for all other applicable skills before responding. See 3.2 for the Mandatory Skill Check Protocol and 7.1 for the full using-superpowers reference.
Skill Activation Decision Flow
Sources: section 5.3 of table of contents
To update Superpowers to the latest version, pull the latest commits in the cloned repository:
The symlink continues to point to ~/.codex/superpowers/skills/, so no symlink changes are needed after a pull. Restart Codex to pick up any new or changed skills.
| Step | Command |
|---|---|
| Remove the symlink | rm ~/.agents/skills/superpowers |
| Remove the cloned repo | rm -rf ~/.codex/superpowers |
On Windows, remove the junction with rmdir "%USERPROFILE%\.agents\skills\superpowers" (do not use /S — junctions are not recursive deletions of the target).
Start a new Codex session and send a prompt that should trigger a skill, such as:
Help me plan a new feature
The agent should invoke the brainstorming skill and follow its structured design process rather than jumping directly into implementation. If no skill fires, confirm the symlink resolves correctly:
For a detailed explanation of how Codex integrates with the skills system at runtime, see 5.3. For how skills are discovered and resolved from disk, see 4.5.
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.