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-harness

Subcommands

Default (no subcommand): init

Arguments

The pre-push gate is the one hook that waits for a human — it reads /dev/tty, so from a non-interactive context it stalls or fails on a terminal that is not there. That is why it is opt-in, and why every path below reads that choice from state rather than re-deciding it. commit-msg stays a default install because it never prompts: it guards the attribution anchor (CLAUDE.md rule 3) by reading the message and deciding, with no /dev/tty and no input. It does still reject — exit 1 on a policy violation, exit 3 when the policy cannot be evaluated — and it rejects interactive and non-interactive commits alike (scripts/commit-msg-guard.sh). The distinction that makes it safe to install by default is prompts vs. rejects, not blocks vs. does not block.

The flag is the opt-in interface — there is no prompt. init must not ask interactively whether to install the gate: this skill runs under Codex sandboxes and in non-interactive setup flows where an unanswered prompt would either hang or be silently defaulted, and a silent default is exactly what opt-in exists to prevent.

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 the git hooks using priority-ordered detection. The mode detection is identical for both hooks; only which hooks are installed differs:

Modes 2–4 write the hook as the file, so check who owns it first

Mode 1 prepends into a shared container; modes 2–4 put the gate — or the guard — at the resolved hook path as that file's whole content. A write there is a delete of whatever was there, and the operator's own pre-push may be the only thing standing between them and something this skill knows nothing about. --with-push-gate is a request to add a guard; taking one away to honour it is not a lesser reading of that request, it is the opposite of it.

So before any dedicated-file mode writes a hook, classify the destination — by content, never by existence:

The marker is the shipped scripts' own second line, so an older shipped version is still recognised as ours and a refresh across versions is not blocked. It is matched as a prefix of a line rather than against the whole file because the byte-for-byte alternative refuses every past version — the one case a refresh most needs to succeed on.

The predicate is deliberately strict in one direction. A hand-edited header stops matching and the install refuses; a foreign file matches only if someone copied our header into it. Refusing an install costs a re-run, and the operator is told which file to move; clobbering costs a hook nobody can get back. The asymmetry decides, exactly as it does for uninstall below — that row already said "only after verifying it is sd0x-owned", and this is the same predicate, stated once, on the side where the file is still there to protect.

pending is the honest record for a refused write: the operator opted in, the wiring did not finish, and the transition matrix already treats pending as a gate to keep — so a later sync retries rather than reading the refusal as a decline. Recording declined would turn their request into an opt-out they never made.

The Husky stanza — prepended, executed, and it hands stdin back

Mode 1 does not write its own file: it goes into .husky/<hook>, beside whatever the project already put there. Two properties of that neighbourhood decide the shape of the stanza, and both were got wrong by the words this section used to carry ("append sourcing"):

So: prepend, and execute. Prepending alone would fix the first and break the project's own hook, which then reads the EOF instead — the same fail-open one file over. The stanza therefore captures the stream once and hands it back:

# >>> sd0x-dev-flow pre-push gate >>>
# No bare command word may decide anything or carry a refusal. This hook runs with the pusher's
# whole environment, and an exported BASH_FUNC_name%% answers `git`, `cat`, `bash`, `mktemp`,
# `[`, `test`, `exec` and `exit` alike. Three things are immune, and every construct here that
# runs BEFORE the verdict, or that enforces it, is built out of only those three:
# `case` (a reserved word, resolved by the grammar), `${x:?}` (fails during expansion, before
# command lookup), and an ABSOLUTE path — bash refuses to import a function whose name contains
# a slash. Everything else that runs before the verdict is inside `bash -p`, which imports no
# functions at all. The two bare words that DO appear — `exec 0<` and `rm -f` — sit after
# `__sd0x_rc` already holds the verdict, and what a shadowed one costs is stated under
# "Two residuals" below rather than wished away by an absolute claim here.
__sd0x_refs=$(/usr/bin/env -u SHELLOPTS -u BASHOPTS -u BASH_ENV -u ENV -u SD0X_PRIV_REEXEC \
  /bin/bash -p -c 'umask 077; f=$(mktemp) || exit 1; cat >"$f" || exit 1; printf %s "$f"')
case "$__sd0x_refs" in
  /*) ;;
  *) __sd0x_abort=''
     : "${__sd0x_abort:?sd0x pre-push gate: could not capture the ref stream}" ;;
esac
/usr/bin/env -u SHELLOPTS -u BASHOPTS -u BASH_ENV -u ENV -u SD0X_PRIV_REEXEC \
  /bin/bash -p -c 'test -r "$1" || exit 0; g=$1; r=$2; shift 2; exec "$BASH" -p -- "$g" "$@" <"$r"' \
  sd0x-pre-push ./.claude/scripts/pre-push-gate.sh "$__sd0x_refs" "$@"
__sd0x_rc=$?
exec 0< "$__sd0x_refs"        # hand git's one-shot stream back to the rest of the hook
rm -f "$__sd0x_refs"          # unlinked, still open on fd 0
case "$__sd0x_rc" in
  0) ;;
  *) __sd0x_abort=''
     : "${__sd0x_abort:?sd0x pre-push gate: refused this push}" ;;
esac
# <<< sd0x-dev-flow pre-push gate <<<

Why the shape is this and not the obvious one. The obvious stanza — __sd0x_gate="$(git rev-parse --show-toplevel)/…", [ -r … ], cat, bash "$gate", exit "$rc" — is what this section shipped for one round, and every command word in it is a hole. Measured 2026-08-21:

That is the same class the gate closes for itself with its privileged re-exec — the stanza simply sat in front of it, outside that protection, and handed the attacker every decision the gate was about to make. The replacement removes the decisions rather than hardening them:

A third residual sits above all of them and is not this stanza's to close: these lines run in the project's own .husky/pre-push shell, whose shebang the project owns. If that shell is bash and the pusher's $BASH_ENV defines /usr/bin/env, the first line here is answered before bash -p is ever reached. The gate's own file closed the same hole for itself by putting -p in its shebang (scripts/pre-push-gate.sh, 2026-08-22) — the one statement early enough, and the one this stanza does not get to write.

Two further residuals, both stated rather than hidden, and both pinned by the hostile-environment test in test/skills/codex-setup.test.js rather than left as prose. A shadowed rm leaks one 0600 temp file per push and cannot open a gate. A shadowed exec leaves the rest of the project's hook reading an already-drained stream — measured TAIL-SAW 0 — because handing stdin back needs a redirection, redirection needs exec, and no POSIX construct reopens fd 0 without it. What that costs is bounded and is not this gate: ours has already decided and enforced by then, and what degrades is the project's own hook. A hook that refuses on an empty ref list still refuses; one that passes on it passes — which is the same exposure it already had before this stanza existed. PATH is outside this boundary for the reason § 4.3 of the implementation doc gives: it cannot be unset, has no trustworthy substitute, and a hostile one is a strictly larger compromise than anything the gate protects.

Line by line, each for a reason that has a failure behind it:

Definition — an intact sd0x block, used by every test in this file that can record installed, so the three of them cannot drift apart. .husky/<hook> holds one when all of:

The third clause is what "carries the sd0x stanza" always meant; stating it as marker balance alone was a round-79 narrowing that would have let doctor report installed × Active over a hook that executes nothing. Presence and intactness are different questions: doctor's "sd0x stanza present" probe greps the opening marker and answers the first, which is all a report needs.

The stanza is prepended even when the Husky hook is created by this skill — writing it first is what makes "prepended" a property of the file rather than of the order two installs happened to run in.

The Husky commit-msg stanza

commit-msg is the hook a flagless init installs (§ Modes), so under Husky it needs its own written-out path — and it is not the push-gate stanza with a name changed. What git hands the two hooks is different, and the whole capture-and-hand-back apparatus above exists for a property commit-msg does not have:

Everything else carries over unchanged, because the threat does: this hook runs with the committer's whole environment, and an exported BASH_FUNC_name%% answers test, bash, exec and exit alike. So the same three immune constructs, for the same reasons the table under the push-gate stanza gives — case, ${x:?}, and an absolute /usr/bin/env — with everything real inside /bin/bash -p.

# >>> sd0x-dev-flow commit-msg guard >>>
# Executed, never sourced — and the reason is NOT the push-gate stanza's, because the guard behaves
# differently and the difference is what matters. The guard re-execs itself privileged through
# `${BASH_SOURCE[0]:-$0}`, which under `.` resolves to the guard, so the re-exec names the right
# file — and then `exec` REPLACES the sourcing shell with it. Measured 2026-08-22: a parent hook
# that sources this guard runs its own first line, hands the process over, and never reaches a
# single line after the `.` — and this stanza is PREPENDED, so everything the project put in its
# own commit-msg hook is what silently stops running. `-u SD0X_PRIV_REEXEC` for the same reason as
# under the push-gate stanza: the guard
# establishes privileged mode through that marker, so an inherited one would make it skip its own
# re-exec. `ALLOW_AI_COAUTHOR` is deliberately NOT unset — it is the narrow opt-in the attribution
# anchor defines, and the guard, not this stanza, is what decides what it may do.
/usr/bin/env -u SHELLOPTS -u BASHOPTS -u BASH_ENV -u ENV -u SD0X_PRIV_REEXEC \
  /bin/bash -p -c 'test -r "$1" || exit 0; g=$1; shift; exec "$BASH" -p -- "$g" "$@"' \
  sd0x-commit-msg ./.claude/scripts/commit-msg-guard.sh "$@"
__sd0x_cm_rc=$?
case "$__sd0x_cm_rc" in
  0) ;;
  *) __sd0x_cm_abort=''
     : "${__sd0x_cm_abort:?sd0x commit-msg guard: refused this commit message}" ;;
esac
# <<< sd0x-dev-flow commit-msg guard <<<

test -r "$1" || exit 0 carries the same meaning as in the push stanza and no more: an uninstalled or half-removed guard leaves the commit alone, so the project's hook behaves as it did before. It is not a substitute for the Active predicate below — a misinstalled guard is what that check is for.

Writing a hook file is not installing it. Verify that git will actually run it before recording installed. Priority 4 only prints the core.hooksPath command; until someone runs it, git still looks in .git/hooks/ and neither the commit-msg guard nor an opted-in push gate ever fires. Recording that as installed would make doctor green over a repository with no active guard at all — the exact failure both hooks exist to prevent. So every mode ends with the same check, and it is a check on git's own answer, not on the file existing:

# What does git itself resolve this hook to?
resolved=$(git rev-parse --git-path "hooks/${hook}")

The comparison depends on the mode, and -ef against $written_path is only correct where git runs the written file directly. Husky is the case that breaks it: the normal modern shape is core.hooksPath=.husky/_, so git runs .husky/_/<hook> — a Husky-owned shim — which sources .husky/<hook>, the container the sd0x stanza was written into. Those are two different files, so an -ef test reports a fully active hook chain as inactive.

The mode numbers below are the priority numbers above — the same four modes, not a second scheme. Mode 1 is Husky, so it takes the Husky row and never the direct-file row; an earlier version of this table grouped "1–3" as direct-file and carried a separate Husky row, leaving a literal reader with two rows claiming mode 1.

$script is per hook, and hard-coding it was a live defect. This row named pre-push-gate.sh unconditionally, which was survivable only while pre-push was the sole hook with a Husky path. It is not any more (§ The Husky commit-msg stanza), and the hard-code breaks in both directions on the default installation: a flagless init installs commit-msg and deliberately leaves the gate absent, so a perfectly working attribution guard records pending; and a repository still carrying an old pre-push-gate.sh records commit-msg as installed after commit-msg-guard.sh has been deleted — doctor green over commits that skip the guard entirely. Each hook's predicate must name its own script.

Identity is not executability. -ef proves the file git resolved is the file we wrote; it says nothing about whether git will run it, and githooks(5) is explicit that a hook without the executable bit is ignored. Mode 1 already required test -x; modes 2–4 did not, so a chmod -x — or a sync overwriting an existing non-executable destination — left doctor reporting a pass over a hook git silently skips. Both halves are now required everywhere.

And identity is not ownership (round 60). -ef asks whether the file git resolved is the file at $written_path; it does not ask whose file that is — and after a refused write those are the same foreign file. Phase 3 classifies the destination by content, declines to clobber a hook it does not own, and records pending; the activation predicate then re-derived $resolved, found it identical to $written_path and executable, and promoted that pending straight back to installed. The sequence needs no adversary: opt in on a repository that already has a pre-push hook, sync, and doctor goes green over a gate that was never installed — the precise inversion of the refusal that produced it. So the ownership predicate is part of the activation predicate, run against the file git resolved rather than the path we intended to write, and it is the same predicate stated in Phase 3 rather than a second one that could drift.

That outcome is terminal pending, and the difference from every other pending is what a later sync may do about it. The ordinary ones are wiring failures — the file is ours, the remedy re-copies it. This one is a file that belongs to somebody else, so re-copying is the clobber the refusal exists to prevent. The remedy is the operator's: move or rename that hook. Until they do, the honest record is pending and the honest doctor verdict is Fail — never a re-copy, and never a promotion to installed.

Every mode's inactive outcome is pending, and the remedy is what differs. The earlier table left modes 1–3 with — in that column, which is not "cannot happen" — mode 2's core.hooksPath can point elsewhere, mode 3's .git/hooks/<hook> can be shadowed — it was simply unstated, so an activation failure there reached a state the schema has no value for. mode is recorded beside status precisely so the remedy can be selected later: doctor prints the recorded mode's line, never a generic one.

⚠️ The .githooks remedy is mode 4's, and must never be printed for Husky. git config core.hooksPath .githooks abandons .husky/_, which stops every Husky hook in the repository — a wider break than the one being reported. A Husky activation failure is repaired inside Husky.

Source scripts from plugin:

The flag is what makes a first install happen. It is not the only thing that writes the hook, and reading it that way is what produced the two defects the matrix below closes: without the flag this skill must still refresh a gate that is already wired, and restore one that was recorded as installed and has since gone missing. Neither is a new install — both are keeping an existing choice true.

So: without the flag and with no gate to keep — the recorded status is absent or unknown, and nothing sd0x-owned is on disk — do not write a pre-push hook and do not leave a partial or disabled one behind. "No gate to keep" means no recorded opt-in of any kind, not merely no recorded installed: pending is an opt-in whose wiring never finished, so it is a gate to keep and takes its own row below. Reading this sentence as "not installed ⇒ decline" is what would write declined over an operator's pending — the exact overwrite the table exists to refuse. The table below is the authority for every combination; this paragraph names only the one row that declines. Record the choice in Phase 5 and report it:

pre-push gate: not installed (opt-in). To add it: /codex-setup sync --with-push-gate

Print that line whenever the gate is skipped, so an operator who expected the old unconditional behaviour learns why the hook is absent at the moment it is skipped, rather than the next time a push is not stopped.

"Skipped" is not "declined" — resolve from disk before recording either. A flagless init re-run on a repository that already has the gate wired must not write declined over it. Nothing on disk changed, so recording a decline would state a choice the operator never made, and the consequences compound rather than surface: doctor reports the declined × present row as a disagreement, and a later plain sync follows the recorded decline and stops re-copying an installed safety hook. So Phase 5 records:

Read the recorded status first, then the disk. Disk alone cannot tell "never chosen" from "chosen, and the wiring has since gone missing", and those two owe opposite actions. Wiring is resolved by the same evidence test sync uses for unknown: Husky stanza present, or a hook file present and verified sd0x-owned.

Two things this table refuses to do, both of which the disk-only version did. It never writes declined over a recorded installed — that states an opt-out the operator never made and disarms a gate they had chosen, after which doctor reads declined × absent as healthy and a plain sync skips it forever. And it never merely relabels: classification is not the update, so every row that concludes installed also refreshes the bytes. An upgraded project is exactly where the wired gate is oldest, and doctor checks activation, not bytes — stale bytes are perfectly active, so they pass it. Activation and hashing are different axes (§ doctor); checking the first is not a reason to skip refreshing the second here.

--with-push-gate is unaffected by the table above: whatever the recorded status was, the flag installs. What it does not do is decide the record — the flag says install it, and the record still says what is actually wired up, which only the mode table's activation test can answer: active → installed, not active → pending with that mode's remedy. Recording installed on the flag's word would put the one status meaning "git will run this hook" on a hook git does not run, which is the same over-claim the mode table exists to prevent — and it would do it precisely where the operator asked for the gate, so the wrong record would look like a granted request. This mirrors sync's unknown row rather than inventing a second rule — the question both answer is the same one, what is actually wired up, and only the flag expresses a choice.

Phase 4: Copy Runner Scripts

Copy these scripts to the host project:

Ensure target directories exist (mkdir -p).

The scripts/pre-push-gate.sh row is conditional because only mode 1 needs it: modes 2–4 install the gate as the hook file, so the copy is the install. Mode 1's stanza instead runs the gate out of line, at .claude/scripts/pre-push-gate.sh — the path /install-scripts also uses. Without this row that path was named by the stanza and written by nothing, so a fresh init --with-push-gate on a Husky project recorded installed while every push evaluated test -r as false and sailed through. The Active predicate above is the other half: the copy can fail, and a recorded installed must mean the gate is reachable, not that a copy was attempted.

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": { "status": "installed", "hash": "<sha1>", "mode": "<husky|hooksPath|direct|fallback>" },
    "pre-push": { "status": "declined" }
  },
  "scripts_installed": {
    "precommit-runner.js": "<sha1>",
    "verify-runner.js": "<sha1>",
    "lib/utils.js": "<sha1>",
    "lib/tree-digest.js": "<sha1>"
  },
  "generated_at": "<ISO8601>"
}

The template above shows the no-flag run, with the commit-msg hook active. When init --with-push-gate installed the hook in Phase 3, the pre-push entry is written like commit-msg: { "status": "installed", "hash": "<sha1>", "mode": "<husky|hooksPath|direct|fallback>" } — the state file must record what this run actually did, never the template verbatim.

commit-msg is not exempt from the activation test, and the installed in the template is the active outcome rather than a constant: it is written through the same Phase 3 mode table as pre-push, so a commit-msg hook that was written but that git does not resolve to is recorded pending with its mode, exactly like any other. Reading the template as a fixed value is the specific misreading to avoid — it would hard-code the one status meaning "git will run this hook" onto a hook git does not run, and doctor would report a repository whose attribution guard never fires as healthy.

status is written explicitly; absence never carries meaning. Every hook entry records one of these, and doctor and sync both branch on it rather than on whether a hash happens to be present:

A deliberate opt-out and a broken install are different states, and a missing field cannot tell them apart — which is why declined is recorded rather than inferred from an absent pre-push key.

Reading a state file written before this contract (entry present, no status): read it as installed. Those files were only ever written after the hook was installed unconditionally, so installed is the true reading, and it is also the safe one — the opposite reading would make sync skip an installed hook and let it drift. An entirely absent pre-push key is unknown, not declined: see doctor and sync below, which resolve it rather than guessing.

Sandbox Adaptation

Detect sandbox: if mkdir -p or file write fails, switch to read-only output mode.

doctor

Checks

…(truncated)