codex-setup

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

1. Find repo root: git rev-parse --show-toplevel
2. Read package.json if present → extract name, scripts.test
3. Read .claude/CLAUDE.md or CLAUDE.md → extract test command pattern
4. Detect plugin root: find scripts/build-codex-artifacts.js relative 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-msg hook
• pre-push-gate.sh → pre-push hook

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

1. Re-run build-codex-artifacts.js → overwrite AGENTS.md
2. Re-copy hook scripts (overwrite if changed)
3. Re-copy runner scripts (overwrite if changed)
4. Update .sd0x/install-state.json with new hashes

References

• references/agents-kernel.md — AGENTS.md kernel template