Codex Setup
Trigger
- Keywords: codex setup, codex init, agents.md, setup codex, initialize codex, codex doctor, codex sync
- After:
npx skills add sd0xdev/sd0x-dev-flow
Subcommands
| Command | Purpose |
|---|---|
init | First-time setup: generate AGENTS.md + install hooks + copy scripts |
doctor | Verify installation integrity (files exist + hash match) |
sync | Re-generate AGENTS.md + update hooks/scripts after skill update |
Default (no subcommand): init
init
Phase 1: Detect Host Context
- Find repo root:
git rev-parse --show-toplevel - Read
package.jsonif present → extractname,scripts.test - Read
.claude/CLAUDE.mdorCLAUDE.md→ extract test command pattern - Detect plugin root: find
scripts/build-codex-artifacts.jsrelative to this skill
Phase 2: Generate AGENTS.md Kernel
node <plugin-root>/scripts/build-codex-artifacts.js \
--project-dir <repo-root> \
--output <repo-root>/AGENTS.md
If the file already exists, warn and ask before overwriting.
Verify output:
- File exists and is non-empty
- Size ≤ 24 KiB (
wc -c < AGENTS.md≤ 24576) - No unresolved placeholders (
{PROJECT_NAME},{VERSION},{TEST_COMMAND})
Phase 3: Multi-Mode Hook Install
Install commit-msg and pre-push git hooks using priority-ordered detection:
| Priority | Condition | Action |
|---|---|---|
| 1 | .husky/ directory exists | Append sourcing to Husky hooks |
| 2 | git config core.hooksPath is set | Install to that path |
| 3 | .git/hooks/ is writable | Direct write |
| 4 | Fallback | Write to .githooks/ + print git config core.hooksPath .githooks |
Source scripts from plugin:
commit-msg-guard.sh→commit-msghookpre-push-gate.sh→pre-pushhook
Phase 4: Copy Runner Scripts
Copy these scripts to the host project:
| Source | Target |
|---|---|
scripts/precommit-runner.js | .sd0x/scripts/precommit-runner.js |
scripts/verify-runner.js | .sd0x/scripts/verify-runner.js |
scripts/lib/utils.js | .sd0x/scripts/lib/utils.js |
Ensure target directories exist (mkdir -p).
Phase 5: Write State File
Write .sd0x/install-state.json to repo root:
{
"sd0x_version": "<from plugin.json>",
"agents_md_hash": "<git hash-object AGENTS.md>",
"agents_md_size": <bytes>,
"hooks_installed": {
"commit-msg": { "hash": "<sha1>", "mode": "<husky|hooksPath|direct|fallback>" },
"pre-push": { "hash": "<sha1>", "mode": "<mode>" }
},
"scripts_installed": {
"precommit-runner.js": "<sha1>",
"verify-runner.js": "<sha1>"
},
"generated_at": "<ISO8601>"
}
Sandbox Adaptation
| Codex sandbox | Behavior |
|---|---|
workspace-write / danger-full-access | Execute all phases automatically |
read-only | Output command list for manual execution |
Detect sandbox: if mkdir -p or file write fails, switch to read-only output mode.
doctor
Checks
| Check | Method | Pass | Fail |
|---|---|---|---|
| AGENTS.md exists | test -f AGENTS.md | File found | Missing |
| AGENTS.md hash match | Compare git hash-object vs state file | Match | Drift detected |
| AGENTS.md size ≤ 24 KiB | wc -c | ≤ 24576 | Oversized |
| Hooks installed | Check hook files exist in detected mode | Present | Missing |
| Scripts installed | Check .sd0x/scripts/ files exist | Present | Missing |
| Version match | Compare state sd0x_version vs current plugin | Match | Update available |
Output a summary table with pass/fail status for each check.
sync
- Re-run
build-codex-artifacts.js→ overwrite AGENTS.md - Re-copy hook scripts (overwrite if changed)
- Re-copy runner scripts (overwrite if changed)
- Update
.sd0x/install-state.jsonwith new hashes
References
references/agents-kernel.md— AGENTS.md kernel template