beads/docs/integrations/codex.md
Chris Sells a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00

1.6 KiB

title
Codex

Use Beads with Codex through the beads skill, managed AGENTS.md guidance, and native Codex hooks.

bd setup codex
bd setup codex --check

Project setup writes:

  • .agents/skills/beads/ for the Beads skill.
  • AGENTS.md with a managed Beads section.
  • .codex/config.toml with [features].hooks = true.
  • .codex/hooks.json with the Beads hook fallback.

bd init runs this project setup by default unless --skip-agents or --stealth is used. Global setup uses bd setup codex --global and writes under $CODEX_HOME when set, otherwise ~/.codex.

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. Use /hooks to inspect or toggle the installed handlers.

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.