2.4 KiB
Codex Integration
Beads supports Codex through the shared beads skill, AGENTS.md guidance, and native Codex lifecycle hooks.
Quick Setup
bd setup codex
Project setup writes:
.agents/skills/beads/for the Beads skill.AGENTS.mdwith a managed Beads section..codex/config.tomlwith[features].hooks = true..codex/hooks.jsonwith the Beads hook fallback.
Global setup uses bd setup codex --global and writes under $CODEX_HOME when set, otherwise ~/.codex.
Plugin-Managed Hooks
The bundled Codex plugin declares "hooks": "./hooks/hooks.json" in plugins/beads/.codex-plugin/plugin.json. On Codex 0.129.0+, use /hooks to inspect or toggle these handlers.
The plugin and bd setup codex fallback install the same lifecycle:
SessionStartwith matcherstartup|resume|clear: injects fullbd primeoutput as developer context.PreCompactwith matchermanual|auto: checksbd prime --memories-onlyand surfaces a warning if Beads context is unavailable.PostCompactwith matchermanual|auto: records that the Codex session needs a Beads refresh.UserPromptSubmit: if a refresh marker exists, injects fullbd primeoutput once and clears the marker.
PreCompact cannot preserve Beads context by printing text; compact hook plain stdout is ignored by Codex. Beads therefore uses PostCompact plus the next UserPromptSubmit to recover context after successful manual or automatic compaction.
Refresh markers are stored in a user cache/temp directory keyed by Codex session_id and workspace path. They are not written to tracked files or to the Beads database.
Manual Fallback
If you do not use the plugin, bd setup codex manages .codex/hooks.json directly. The equivalent manual shape is:
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear",
"hooks": [{ "type": "command", "command": "bd codex-hook SessionStart" }]
}
],
"PreCompact": [
{
"matcher": "manual|auto",
"hooks": [{ "type": "command", "command": "bd codex-hook PreCompact" }]
}
],
"PostCompact": [
{
"matcher": "manual|auto",
"hooks": [{ "type": "command", "command": "bd codex-hook PostCompact" }]
}
],
"UserPromptSubmit": [
{
"hooks": [{ "type": "command", "command": "bd codex-hook UserPromptSubmit" }]
}
]
}
}
Ensure config.toml enables:
[features]
hooks = true