> ## Documentation Index
> Fetch the complete documentation index at: https://beads.gascity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Set up beads for Codex with the beads skill, a managed AGENTS.md section, and native hooks that survive compaction

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

```bash theme={null}
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.

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.

The Beads Codex plugin stores hooks at `plugins/beads/.codex-plugin/hooks/hooks.json` and declares them in `plugins/beads/.codex-plugin/plugin.json` as `"hooks": "./.codex-plugin/hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`.

## Manual Fallback

If you manage `.codex/hooks.json` by hand instead of running `bd setup codex`, the equivalent shape is:

```json theme={null}
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear",
        "hooks": [{ "type": "command", "command": "bd codex-hook SessionStart", "statusMessage": "Loading Beads context" }]
      }
    ],
    "PreCompact": [
      {
        "matcher": "manual|auto",
        "hooks": [{ "type": "command", "command": "bd codex-hook PreCompact", "statusMessage": "Checking Beads context" }]
      }
    ],
    "PostCompact": [
      {
        "matcher": "manual|auto",
        "hooks": [{ "type": "command", "command": "bd codex-hook PostCompact", "statusMessage": "Scheduling Beads context refresh" }]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [{ "type": "command", "command": "bd codex-hook UserPromptSubmit", "statusMessage": "Refreshing Beads context" }]
      }
    ]
  }
}
```

Then ensure `.codex/config.toml` enables:

```toml theme={null}
[features]
hooks = true
```