Adds a bundled TypeScript extension under .pi/skills/planning-with-files/extensions/planning-with-files/ that maps Pi lifecycle events onto the same behavior the skill provides on Claude Code (PR #157 by @TomXPRIME). Event surface: session_start, before_agent_start, tool_call, tool_result, agent_end, session_before_compact, session_shutdown, input. Four modes: auto (DeepSeek-aware), parity, cache-safe, notify. Attestation gate shares the v2.37 .attestation file. Four slash commands registered (/plan-status, /plan-attest, /plan-goal, /plan-loop). 12 new contract tests. Fixes docs/codex.md to use the canonical [features] hooks = true key (Issue #154 by @DLI1996), with a deprecated-alias note so users on older configs keep working. Version bumped to 2.39.0 across 14 SKILL.md variants, plugin.json, marketplace.json, CITATION.cff via scripts/bump-version.py. .pi npm scheme bumped 1.0.1 -> 1.1.0 for the extension surface. .continue, .gemini, .kiro lag intentionally. Tests: 110 pass, 2 pre-existing Windows exec-bit failures unrelated to this release.
186 lines
5.4 KiB
Markdown
186 lines
5.4 KiB
Markdown
# 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
|