---
title: OpenPlanr in Codex
description: Install OpenPlanr's skills in Codex as one plugin, as individual skills, or as project rules, and invoke them with a dollar sign.
url: https://openplanr.dev/docs/hosts/codex
updated: 2026-10-06
related:
  - https://openplanr.dev/docs/hosts.md
  - https://openplanr.dev/docs/hosts/claude-code.md
  - https://openplanr.dev/docs/hosts/cursor.md
---

# OpenPlanr in Codex

In Codex, OpenPlanr's skills run inside your Codex session. Skills and the openplanr CLI add no model calls or telemetry.

## Install

Run the setup step from [Install and set up OpenPlanr](https://openplanr.dev/docs/get-started/install.md) and choose Codex. Setup shows exactly what it will write before it writes anything. User scope installs once per machine and is the default; project scope installs into the current repository. `CODEX_HOME` selects the Codex profile that setup writes to.

Codex supports 3 install modes, chosen with setup's `--skill-mode` option:

- **One plugin** (`unified-plugin`): the `planr` plugin, with every skill in it.
- **Individual skills** (`direct`): each skill installed on its own and invoked by its bare name.
- **Project rules** (`project-rule`): the skills installed as rules in the current repository.

Codex uses one install mode at a time. Preview a switch with a dry run before you change modes; setup's `--replace-managed` option replaces only OpenPlanr's own discovery files when you switch.

Restart Codex after setup so it loads the new skills.

## Invoke a skill

Type a dollar sign and the skill's name. With the plugin installed, add the plugin's `planr:` prefix after the dollar sign.

Codex can also invoke a skill on its own when your request matches the skill's description. When a skill needs a decision from you, it asks with Codex's native question prompt where one is available. Each skill also carries a display name for Codex, such as OpenPlanr Spec.

Set Commands for to Codex, in the page header or in the navigation menu on a phone, and every skill command in these docs shows its Codex form, with the plugin form in the note under it.

## Let Codex see every skill

Generate the guidance so Codex knows every skill and when to reach for it:

```bash
openplanr rules generate --target codex
```

This adds an `## OpenPlanr capabilities` section to `AGENTS.md` between managed markers. Your own content outside the markers is left alone.

## When something goes wrong

- **A skill is missing.** Run `openplanr doctor --json`, which lists every managed installation. Confirm that setup targeted Codex with the scope and mode you expect, then restart Codex.
- **Update only Codex.** `openplanr runtime update codex` refreshes Codex alone and keeps its saved scope and discovery mode.
- **Undo setup.** `openplanr runtime rollback` restores the last pre-setup state for every managed agent.

More fixes are in [Troubleshooting](https://openplanr.dev/docs/get-started/troubleshooting.md), and [the host matrix](https://openplanr.dev/docs/hosts.md) shows what differs between agents.