Skip to content
OpenPlanr Docs
LearnGitHub (opens in a new tab)

OpenPlanr in Codex

Install OpenPlanr's skills in Codex as one plugin, as individual skills, or as project rules, and invoke them with a dollar sign.

OpenPlanr's skills run inside your Codex session. Install individual skills with the standard installer, or use the companion CLI to manage the unified planr plugin.

Install individual skills

Run this in a normal terminal from your project:

bash
npx skills add openplanr/OpenPlanr

Choose the skills, Codex, and Project or Global scope. Project scope is the default. If Codex is the only detected host, the installer may select it automatically.

Restart Codex after installation. These source skills retain names such as planr-ship, invoked with a dollar sign followed by planr-ship. They include their supporting references and schemas; no OpenPlanr build step is needed. They do not install the plugin's native role definitions.

Install the unified plugin

For a CLI-managed plugin, install the companion CLI and run:

bash
openplanr setup --runtime codex --scope user --skill-mode unified-plugin

Setup shows what it will write before applying changes. User scope installs once per machine; project scope installs into the current repository. CODEX_HOME selects the Codex profile that setup writes to.

CLI-managed setup also supports --skill-mode direct for bare-named skills such as ship, and --skill-mode project-rule for project rules. These names differ from the planr-ship source skills installed by npx skills.

Choose one installation method per host to avoid duplicate discovery. Preview a switch between CLI-managed modes with --dry-run; --replace-managed replaces only OpenPlanr's own discovery files. Restart Codex after setup.

Invoke a skill

Type a dollar sign followed by the installed name:

InstallationExample
Unified pluginplanr:ship
Standard skills installerplanr-ship
CLI-managed direct skillsship

Codex can also select a skill when your request matches its description. Use its skill picker to confirm the installed name. Command examples elsewhere may use CLI-managed direct names such as ship; use planr-ship for a source skill or planr:ship for the plugin.

Add the companion CLI when needed

Diagram rendering, local studios, planning validation, diagnostics, and integrations use the companion CLI:

bash
npm install -g openplanr

See Install and set up OpenPlanr for requirements and structured planning setup.

When something goes wrong

  • A skill is missing. Confirm which installation method and scope you used, then restart Codex and check its skill picker.
  • Individual skills need an update. Use npx skills update for skills installed through that installer.
  • A CLI-managed installation needs diagnosis. Run openplanr doctor --json. openplanr runtime update codex refreshes a CLI-managed installation while preserving its saved scope and discovery mode.
  • Undo CLI-managed setup. openplanr runtime rollback restores the last pre-setup state. For other installations, use the installer or plugin manager that installed them.

More fixes are in Troubleshooting, and the host matrix shows what differs between agents.