planning-with-files/docs/codex.md

Codex Setup

Using planning-with-files with OpenAI Codex.

---

Overview

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 automation

The 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 = true in ~/.codex/config.toml. The older codex_hooks = true still works as a deprecated alias.

---

Installation

Method 1: Workspace Installation (Recommended)

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

Method 2: Personal Installation

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 the SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop entries into your existing file.

Enable Hooks in config.toml

Ensure 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.

Verification

codex --version
codex features list | rg '^codex_hooks\s'
ls -la ~/.codex/skills/planning-with-files/SKILL.md
ls -la ~/.codex/hooks.json ~/.codex/hooks/

If codex_hooks does not appear in codex features list, upgrade Codex before troubleshooting the skill.

---

How It Works

Hooks

Codex reads hooks from:

1. .codex/hooks.json in your project root
2. ~/.codex/hooks.json for your global install

This integration includes all five Codex lifecycle hooks:

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
Stop	Blocks once when phases are incomplete, then falls back to a follow-up reminder

The Three Files

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

---

Team Workflow

Workspace Installation

With workspace installation (.codex/ committed to your repo):

• Everyone on the team gets the same skill and hooks
• The Codex setup is version controlled with the project
• Updates ship through normal git review

Personal Installation

With personal installation (~/.codex/):

• You can use the skill across all projects
• You keep your setup even if you change repositories
• Existing global hooks may need manual merging

---

Troubleshooting

Hooks Not Running?

1. Check that hooks = true (or the deprecated alias codex_hooks = true) is present in ~/.codex/config.toml
2. Verify .codex/hooks.json or ~/.codex/hooks.json exists
3. Restart Codex after adding or changing hooks
4. Run codex features list | rg '^(hooks|codex_hooks)\s'

Already Using Other Global Hooks?

That is fine, but do not overwrite your existing ~/.codex/hooks.json. Merge the planning-with-files entries instead.

Seeing Duplicate Hook Messages?

Avoid installing the same planning-with-files hooks in both places at once:

• workspace .codex/hooks.json
• global ~/.codex/hooks.json

If you enable both, Codex may run both sets of hooks and duplicate the reminders.

Windows Support

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.

---

Learn More

• Installation Guide
• Quick Start
• Workflow Diagram

---

Support

• GitHub Issues: https://github.com/OthmanAdi/planning-with-files/issues
• OpenAI Codex Hooks Docs: https://developers.openai.com/codex/hooks
• OpenAI Codex Skills Docs: https://developers.openai.com/codex/skills