OpenAI Codex CLI

This guide covers using Flow with the OpenAI Codex CLI. You will learn:

• How to install the Flow harness for Codex
• Where Flow writes its files in a Codex project
• How to invoke Flow's skills

Overview

Flow installs into the Codex CLI through its standard files. The harness docs index becomes a managed block in AGENTS.md, and every Flow skill becomes a skill under .agents/skills/.

This page covers only the Codex specifics. If you have not added the Flow package to your project yet, start with the Installation guide.

Installing for Codex

Run the harness installer and select OpenAI Codex CLI at the agent prompt:

node ace flow:install

Flow detects Codex automatically when an .agents directory or an AGENTS.md file is present, so it is usually pre-selected. To target it directly and skip the agent prompt, pass the --agent flag:

node ace flow:install --agent=codex

Where Flow writes its files

Installing for Codex adds the following to your project:

• .flow/docs/ holds the harness docs. This location is the same for every agent.
• AGENTS.md gains the managed harness block: the docs index and the project facts. Flow upserts this block between comment markers and leaves the rest of the file untouched.
• .agents/skills/ gains one directory per installed skill, each named flow-<skill>. The brief skill, for example, lands at .agents/skills/flow-brief/SKILL.md, alongside any reference files that skill ships.

The .flow/docs/ directory and the flow- skill directories are added to .gitignore, because the harness is regenerated by re-running the installer.

Invoking skills

Flow's skills are invoked as slash commands. The skill directory name is also the command name, so the skill at .agents/skills/flow-brief/ is invoked as /flow-brief:

/flow-brief checkout-redesign

Every spec-driven workflow skill follows the same /flow-<name> pattern: /flow-blueprint, /flow-assert, /flow-build, /flow-sync, /flow-archive. A skill name with a dot uses a dash in the command, so the build.tdd skill is /flow-build-tdd.

The workflow skills install with implicit invocation disabled, so Codex will not trigger them on its own. They run only when you type the command, keeping you in control of when the workflow advances. Engineering skills such as CRUDDY controllers are an exception: Codex may invoke them automatically when it recognizes a relevant task, and you can still call them explicitly.

Next steps

• Spec-driven development explains the workflow these skills implement.
• Knowledge base describes the harness docs Codex reads from.