docs/codex.md
Using planning-with-files with OpenAI Codex.
Codex discovers skills from .codex/skills/ and hooks from .codex/hooks.json or ~/.codex/hooks.json.
This integration includes both:
.codex/skills/planning-with-files/ for the skill itself.codex/hooks.json plus .codex/hooks/ for lifecycle automationThe hook behavior reuses the same mature shell scripts as the Cursor integration, with a thin Codex adapter layer for the differences in hook protocol.
Important: Codex hooks require
hooks = truein~/.codex/config.toml. The oldercodex_hooks = truestill works as a deprecated alias.
Share the skill and hooks with your whole team by committing .codex/ to your repository:
# In your project repository
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy the Codex integration to your repo
cp -r /tmp/planning-with-files/.codex .
# Commit to share with team
git add .codex/
git commit -m "Add planning-with-files skill for Codex"
git push
# Clean up
rm -rf /tmp/planning-with-files
Install just for yourself:
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy the skill
mkdir -p ~/.codex/skills
cp -r /tmp/planning-with-files/.codex/skills/planning-with-files ~/.codex/skills/
# Copy the hook scripts
mkdir -p ~/.codex/hooks
cp -r /tmp/planning-with-files/.codex/hooks/* ~/.codex/hooks/
# Copy hooks.json
# If you already have ~/.codex/hooks.json, merge the planning-with-files entries manually
cp /tmp/planning-with-files/.codex/hooks.json ~/.codex/hooks.json
# Clean up
rm -rf /tmp/planning-with-files
Note: If you already have a
~/.codex/hooks.json, do not overwrite it blindly. Merge theSessionStart,UserPromptSubmit,PreToolUse,PostToolUse, andStopentries into your existing file.
config.tomlEnsure your ~/.codex/config.toml contains:
[features]
hooks = true
If you already have a [features] section, add hooks = true under it instead of creating a duplicate section. codex_hooks = true is still accepted as a deprecated alias for users on older configs.
codex --version
codex features list | rg '^(hooks|codex_hooks)\s'
ls -la ~/.codex/skills/planning-with-files/SKILL.md
ls -la ~/.codex/hooks.json ~/.codex/hooks/
If neither hooks nor the deprecated alias codex_hooks appears in codex features list, upgrade Codex before troubleshooting the skill.
Codex reads hooks from:
.codex/hooks.json in your project root~/.codex/hooks.json for your global installThis integration includes the Codex lifecycle hooks used by the adapter:
| Hook | What It Does |
|---|---|
| SessionStart | Runs session-catchup.py, then injects active plan context |
| UserPromptSubmit | Re-injects plan and recent progress on every user message |
| PreToolUse | Re-reads the first 30 lines of task_plan.md before Bash |
| PostToolUse | Reminds the agent to update progress.md after Bash activity |
| PreCompact | Reminds the agent to flush progress.md and task_plan.md before compaction |
| Stop | Emits an advisory progress-sync reminder when phases are incomplete (non-blocking since v3.1.0) |
Once activated, the skill creates and maintains:
| File | Purpose | Location |
|---|---|---|
task_plan.md | Phases, progress, decisions | Your project root |
findings.md | Research, discoveries | Your project root |
progress.md | Session log, test results | Your project root |
codex exec)A one-shot session that shares a working directory with an active plan gets the
plan context injected even though it never opted in: a CI review bot, a
read-only research agent, or a nested orchestrator can end up "reconciling the
plan" instead of doing its own job, and may mutate task_plan.md and
progress.md that belong to another session (issue #195).
Set PLANNING_DISABLED=1 to disable all planning-with-files hooks for that
invocation only:
PLANNING_DISABLED=1 codex exec -o review.md '$code-review review this branch'
PLANNING_DISABLED=1 codex exec -C <repo> -s read-only '<research prompt>'
With the variable set, every hook (SessionStart, UserPromptSubmit, PreToolUse,
PostToolUse, PreCompact, Stop) exits before reading the plan: no context
injection, no follow-up messages, no plan-file writes. PreToolUse still emits
its allow decision so tool calls proceed normally. Interactive sessions in
the same directory are unaffected. The same variable is honored by the
canonical Claude Code dispatchers (inject-plan.sh, gate-stop.sh,
check-complete.sh/.ps1), so it works for CI automation on any platform
whose hooks route through those scripts.
With workspace installation (.codex/ committed to your repo):
With personal installation (~/.codex/):
hooks = true (or the deprecated alias codex_hooks = true) is present in ~/.codex/config.toml.codex/hooks.json or ~/.codex/hooks.json existscodex features list | rg '^(hooks|codex_hooks)\s'That is fine, but do not overwrite your existing ~/.codex/hooks.json. Merge the planning-with-files entries instead.
Avoid installing the same planning-with-files hooks in both places at once:
.codex/hooks.json~/.codex/hooks.jsonIf you enable both, Codex may run both sets of hooks and duplicate the reminders.
OpenAI's current Codex hooks documentation says hooks are disabled on Windows. The skill files can still be installed there, but the hook automation is currently for macOS/Linux Codex environments.