docs(codex): wire the compaction hook into README and codex-tools, add drift-cure footer

README gains the hook install step for Codex users (hooks.json merge,
one-time trust prompt, --dangerously-bypass-hook-trust for headless
automation). codex-tools.md aligns its claims with the mechanism — the
dispatch rules bind every spawn, the printed hints appear at scripted
boundaries, and the hook covers post-compaction re-grounding — and adds
a section telling controllers compaction sheds these instructions and
to treat every printed hint as authoritative.

The hints file gains a drift-cure footer both scripts print after the
role line: in the instrumented run that broke post-compaction,
reprinted hints alone did not heal the already-broken dispatch pattern
across three subsequent boundaries — recovery text must name the drift
and prescribe the re-read.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Drew Ritter
2026-07-23 12:23:17 -07:00
parent 1744d69413
commit 5ab3297ad7
6 changed files with 71 additions and 2 deletions

View File

@@ -98,6 +98,41 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
- Select `Install Plugin`.
#### Codex: compaction re-injection hook (recommended)
Codex compacts long sessions, replacing the transcript with a summary that
drops Superpowers' skill instructions mid-run — long autonomous workflows
(like subagent-driven-development) then drift back to harness defaults.
Claude Code re-injects the bootstrap after every compaction; this hook
restores the same behavior on Codex (0.145+).
Merge `hooks/hooks-codex.json.example` from your Superpowers install into
`~/.codex/hooks.json`, replacing the placeholder with the absolute path to
your install:
```json
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "bash \"/path/to/superpowers/hooks/session-start-codex\"",
"timeout": 30
}
]
}
]
}
}
```
Codex asks you to trust the hook once, the first time it runs in the app.
Headless automation (CI, eval harnesses) must pass
`--dangerously-bypass-hook-trust` instead, because untrusted hooks are
skipped silently.
### Cursor
- In Cursor Agent chat, install from marketplace: