Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.
The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).
Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.
Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).
Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
75 lines
2.9 KiB
Markdown
75 lines
2.9 KiB
Markdown
---
|
|
title: Codex
|
|
---
|
|
|
|
Use Beads with Codex through the `beads` skill, managed `AGENTS.md` guidance, and native Codex hooks.
|
|
|
|
```bash
|
|
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
|
|
{
|
|
"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
|
|
[features]
|
|
hooks = true
|
|
```
|