beads/website/docs/integrations/codex.md
Chris DiMartino 0afd3d5b94
fix(codex): ship hook release safely
Move Codex native hook metadata under the Codex-only plugin directory so Claude keeps using only its inline `bd prime` hooks.

Leave release version bumps to the maintainer release flow while documenting hook metadata isolation under Unreleased.

Refs #3924.

_codex-gpt-5.5-medium on behalf of matt wilkie_
2026-05-27 13:19:41 -07:00

27 lines
1.2 KiB
Markdown

---
id: codex
title: Codex
sidebar_position: 2
---
# Codex Integration
Use Beads with Codex through the `beads` skill, managed `AGENTS.md` guidance, and native Codex hooks.
```bash
bd setup codex
bd setup codex --check
```
Codex 0.129.0+ supports `/hooks`, compact lifecycle hooks, and hook-provided developer context. Beads uses that lifecycle to inject `bd prime` on session start and recover context after compaction.
## Hook Lifecycle
- `SessionStart` (`startup|resume|clear`) injects full `bd prime` output.
- `PreCompact` (`manual|auto`) checks `bd prime --memories-only` and warns if Beads context is unavailable.
- `PostCompact` (`manual|auto`) records that the session needs a Beads refresh.
- `UserPromptSubmit` injects full `bd prime` once after compaction, then clears the refresh marker.
`PreCompact` alone does not inject context because Codex ignores plain stdout from compact hooks. The post-compact marker plus first-prompt refresh is the reliable recovery path.
The Beads Codex plugin stores hooks at `plugins/beads/.codex-plugin/hooks/hooks.json` and declares them as `"hooks": "./hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`.