sd0xdev/sd0x-dev-flow/codex-setup
Claude Code and agent skill by sd0xdev/sd0x-dev-flow
- community
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-setupSKILL.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
| Command | Purpose | |
|---|---|---|
init | First-time setup: generate AGENTS.md + install the commit-msg hook + copy scripts | |
doctor | Verify installation integrity: files exist, AGENTS.md hash matches, and each recorded hook is active — hook bytes are sync's axis, not this one (§ doctor) | |
sync | Re-generate AGENTS.md + update installed hooks/scripts after skill update |
Default (no subcommand): init
Arguments
| Flag | Applies to | Effect | |
|---|---|---|---|
--with-push-gate | init, sync | Install 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
- 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
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:
| Priority | Condition | Action | |
|---|---|---|---|
| 1 | .husky/ directory exists | Copy 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 | |
| 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 — 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:
| Destination | Action | |
|---|---|---|
| Absent, or present and empty | Write. 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 hook | Overwrite. This is a refresh of our own file, which is what sync exists to do | |
| Anything else | Do 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"):
| Property | Consequence | Measured 2026-08-21 | |
|---|---|---|---|
| git delivers the ref list on stdin, once | An earlier consumer in the same hook takes it, and the gate then reads EOF — zero refs, nothing protected, nothing rewritten, exit 0 | An 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 $0 | The gate's privileged re-exec, which then read exec … bash -p "$0" "$@", named the Husky hook rather than the gate | The 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:
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:
| Injected | What 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
- SKILL.md in the repositoryCheckingskills/codex-setup/SKILL.md
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
[](https://verified-skill.com/skills/sd0xdev/sd0x-dev-flow/codex-setup)