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

> **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 '^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](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
