Codex Installation Guide

Prerequisites

• OpenAI Codex CLI installed
• Git installed

Installation Steps

Option 1: Let Codex Install Automatically (Recommended)

Tell Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

Option 2: Manual Installation

macOS / Linux:

1. Clone the repository:

   git clone https://github.com/obra/superpowers.git ~/.codex/superpowers

2. Create the skills symlink:

   mkdir -p ~/.agents/skills
   ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

3. Restart Codex.

Windows (PowerShell):

1. Clone the repository:

   git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"

2. Create the skills junction:

   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
   cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

3. Restart Codex.

Subagent Features (Optional)

To use subagent skills like dispatching-parallel-agents and subagent-driven-development, enable the collab feature in your Codex config:

[features]
collab = true

How It Works

Codex has native skill discovery — it scans ~/.agents/skills/ at startup, parses SKILL.md frontmatter, and loads skills on demand. Superpowers skills are made visible through a single symlink:

~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/

Verify Installation

ls -la ~/.agents/skills/superpowers

You should see a symlink pointing to your superpowers skills directory.

Configuration File Locations

• Skills directory: ~/.codex/superpowers/skills/
• Personal skills: ~/.agents/skills/

Updating

cd ~/.codex/superpowers && git pull

Skills update instantly through the symlink — no restart needed.

Uninstalling

macOS / Linux:

rm ~/.agents/skills/superpowers
rm -rf ~/.codex/superpowers  # Optional: delete the clone

Windows (PowerShell):

Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"  # Optional

Troubleshooting

Skills not showing up

1. Verify the symlink: ls -la ~/.agents/skills/superpowers
2. Check skills exist: ls ~/.codex/superpowers/skills
3. Restart Codex — skills are discovered at startup

Windows junction issues

Junctions normally work without special permissions. If creation fails, try running PowerShell as administrator.

Migrating from old version

If you installed Superpowers before native skill discovery:

1. Update the repo: cd ~/.codex/superpowers && git pull
2. Create the skills symlink (see installation steps)
3. Remove the old bootstrap block from ~/.codex/AGENTS.md
4. Restart Codex