othmanadi--planning-with-files/docs/codex.md

# Codex Setup

Using planning-with-files with [OpenAI Codex](https://developers.openai.com/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. On Windows those same scripts run through an auto-resolved Git Bash (see [Windows Support](#windows-support)).

> **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:

```bash
# 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:

```bash
# 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:

```toml
[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

```bash
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.

---

## 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 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) |

### 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 |

### Opting out for one-shot runs (CI, `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:

```bash
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.

---

## 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

Hooks run on Windows. Codex reads a per-hook `commandWindows` override from `.codex/hooks.json` on Windows and the POSIX `command` everywhere else, so macOS and Linux are unchanged.

On Windows every hook routes through `.codex\hooks\pwf-hook.cmd`, which finds a real Python (`py -3`, falling back to `python`) and never the Microsoft Store `python3` alias. The four Python hooks run their `.py` entry point directly. The three shell hooks (SessionStart, UserPromptSubmit, PreCompact) route through `run_sh.py`, which locates the Git for Windows `sh.exe` and runs the same shell scripts the macOS/Linux hooks use.

Requirements on Windows:

- `hooks = true` in `~/.codex/config.toml` (same as every platform).
- Python reachable through the `py` launcher (installed by the python.org installer) or on PATH as `python`. If you only have `python`, the launcher falls back to it automatically. The Microsoft Store `python3` alias is skipped on purpose.
- Git for Windows installed, for the three shell-backed hooks. The launcher finds `sh.exe` even when Git's `usr\bin` is not on your PATH, which is the default install layout. Without Git for Windows those three hooks stay silent and the four Python hooks still work.

Use the workspace install (Method 1) on Windows: the `commandWindows` entries use relative `.codex\...` paths resolved against your project directory. A global `~/.codex` install needs absolute paths in `commandWindows`.

---

## Learn More

- [Installation Guide](installation.md)
- [Quick Start](quickstart.md)
- [Workflow Diagram](workflow.md)

---

## 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