sd0xdev/sd0x-dev-flow/codex-setup

Claude Code and agent skill by sd0xdev/sd0x-dev-flow

Trust tier 2
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Initialize sd0x-dev-flow infrastructure for Codex CLI and other non-Claude agents. Generates AGENTS.md, installs the commit-msg hook, copies runner scripts. The pre-push gate is opt-in via --with-push-gate. Use when setting up a new project or after updating skills.

Install

npx vskill@latest install sd0xdev/sd0x-dev-flow/codex-setup

SKILL.md

The same SKILL.md was published earlier as sd0xdev/sd0x-dev-flow/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

CommandPurpose
initFirst-time setup: generate AGENTS.md + install the commit-msg hook + copy scripts
doctorVerify installation integrity: files exist, AGENTS.md hash matches, and each recorded hook is active — hook bytes are sync's axis, not this one (§ doctor)
syncRe-generate AGENTS.md + update installed hooks/scripts after skill update

Default (no subcommand): init

Arguments

FlagApplies toEffect
--with-push-gateinit, syncInstall pre-push-gate.sh as the pre-push hook. Off by default

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
bash
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:

PriorityConditionAction
1.husky/ directory existsCopy the hook's script to .claude/scripts/, then prepend that hook's executing stanza below to .husky/<hook> — commit-msg-guard.sh into .husky/commit-msg, and (only under --with-push-gate) pre-push-gate.sh into .husky/pre-push. Two stanzas, not one: they are shaped by what git hands each hook, and § The Husky commit-msg stanza says where they differ
2git config core.hooksPath is setInstall to that path
3.git/hooks/ is writableDirect write
4FallbackWrite to .githooks/ + print git config core.hooksPath .githooks — the write alone does not arm the hook; see below
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:

DestinationAction
Absent, or present and emptyWrite. Nothing is lost
sd0x-owned — one of the first 20 lines is exactly # <script> - followed by that script's own summary, where <script> is pre-push-gate.sh or commit-msg-guard.sh per hookOverwrite. This is a refresh of our own file, which is what sync exists to do
Anything elseDo not write. Record pending, and report: <hook>: <resolved> already exists and is not sd0x-owned — the gate was not installed; move or rename that hook, then re-run

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"):

PropertyConsequenceMeasured 2026-08-21
git delivers the ref list on stdin, onceAn earlier consumer in the same hook takes it, and the gate then reads EOF — zero refs, nothing protected, nothing rewritten, exit 0An existing while read … loop ahead of the gate turned a protected-branch rewrite that the gate refuses with exit 1 into an allowed push
./source does not change $0The gate's privileged re-exec, which then read exec … bash -p "$0" "$@", named the Husky hook rather than the gateThe parent hook's first line printed twice — once at $-=hB, once at hpB — i.e. the user's whole pre-push re-ran under a privileged shell, and the gate never ran as the gate. The gate has since switched that word to ${BASH_SOURCE[0]:-$0}, which resolves correctly under source, and an ordinary source of the gate now refuses (2026-08-22) — so no supported caller reaches this defect. Not "closed entirely": the refusal compares against $0, which a sourcing caller supplies, and a forged one walks past it (4-implementation.md § 4.3, Round 54). Row 1 above was already reason enough on its own

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:

sh
# >>> 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:

InjectedWhat the obvious stanza did
BASH_FUNC_git%%='() { echo /definitely-missing; }'resolved the gate to a path that does not exist, so [ -r … ] was false and the hook continued with no gate and exit 0
BASH_FUNC_cat%%='() { :; }'discarded the ref stream; the gate then read an empty file, found no refs, and exited 0
BASH_FUNC_bash%%='() { return 0; }'never launched the gate at all, and reported success
BASH_FUNC_exec%% / BASH_FUNC_exit%%exec and exit are builtins, so both are shadowable: the refusal path became a no-op

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:

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 91 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
188
Repository forks
24
7-day trend score
26

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 21 May 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/sd0xdev/sd0x-dev-flow/codex-setup/badge)](https://verified-skill.com/skills/sd0xdev/sd0x-dev-flow/codex-setup)

Something wrong with this skill or its page? Tell us.