docs(codex-first): cover ChatGPT-app-bundled Codex on PATH by notorious-d-e-v · Pull Request #29 · steipete/agent-scripts

notorious-d-e-v · 2026-07-14T04:53:16Z

Codex merged into the ChatGPT desktop app (July 2026), so the CLI now also ships as a bundled binary at /Applications/ChatGPT.app/Contents/Resources/codex.

Document both install shapes and the symlink trap: the bundled binary resolves sibling helpers (e.g. codex-code-mode-host) relative to its invocation path, so symlinking it onto PATH makes exec fail with "the workspace execution host is missing". Use an exec-wrapper or the standalone installer instead.

Review updates (addresses ClawSweeper findings)

Scoped the no-symlink rule to the app-bundled binary (P2). Package-manager symlinks/shims from npm/standalone installs are fine and no longer discouraged — the caveat now applies only to the ChatGPT.app binary, which is the case that actually breaks.
Made the wrapper recipe non-destructive (P2). It now mkdir -p ~/.local/bin first and skips if a launcher already exists, so it works on a fresh app-only machine and never clobbers an existing codex.

Behavior proof (codex-cli 0.144.0-alpha.4, macOS)

Isolated repro — identical prompt and flags (exec --yolo --skip-git-repo-check -m gpt-5.6-sol -c model_reasoning_effort=low --disable fast_mode), only the launcher varies:

Launcher	Result
symlink → bundled binary	❌ `Unable to create ok.txt: the workspace execution host is missing` (agent runs, file edit fails)
exec-wrapper → bundled binary	✅ `ok.txt` created, contents `hi`
bundled binary directly (control)	✅ `ok.txt` created, contents `hi`

# codex version
codex-cli 0.144.0-alpha.4

## SYMLINK on PATH
Unable to create `ok.txt`: the workspace execution host is missing, so no files were changed.
[exit=0] ok.txt=[]

## EXEC-WRAPPER
Changed: `ok.txt` — contains exactly `hi`.
[exit=0] ok.txt=[hi]

## DIRECT (control)
Created `ok.txt` containing exactly `hi`.
[exit=0] ok.txt=[hi]

Same binary in all three runs; the only difference is whether it was reached through a symlink. That isolates the failure to symlink invocation of the app-bundled binary (helper resolution relative to argv[0]), not symlinks in general — which is why the fix scopes the warning to the app bundle.

Codex merged into the ChatGPT desktop app (July 2026), so the CLI now also ships as a bundled binary at /Applications/ChatGPT.app/Contents/Resources/codex. Document both install shapes and the symlink trap: the bundled binary resolves sibling helpers (e.g. codex-code-mode-host) relative to its invocation path, so symlinking it onto PATH makes exec fail with "the workspace execution host is missing" (agent runs, file edits fail). Use an exec-wrapper or the standalone installer instead. Reproduced on codex-cli 0.144.0-alpha.4: symlink -> fail, exec-wrapper -> ok, direct binary -> ok.

clawsweeper · 2026-07-14T11:01:59Z

Codex review: needs changes before merge. Reviewed July 16, 2026, 9:17 AM ET / 13:17 UTC.

Summary
The PR documents safe PATH exposure for the ChatGPT desktop app’s bundled Codex executable, including an exec-wrapper and standalone installer alternative.

Reproducibility: not applicable. as a bug classification, although the PR supplies convincing live CLI output reproducing the documented symlink failure and validating the wrapper behavior.

Review metrics: 1 noteworthy metric.

Documentation surface: 1 skill file; +8/-1 lines. All user impact is concentrated in one copy-paste shell recipe, making the remaining defects narrow but directly actionable.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Ensure ~/.local/bin is placed on PATH before presenting the wrapper as exposed.
Treat both existing files and dangling symlinks as occupied launcher paths.

Risk before merge

[P1] Users following the current recipe on a fresh app-only machine can create the wrapper yet remain unable to invoke codex because its directory is not on PATH.
[P1] A pre-existing dangling launcher symlink can redirect the documented write to an unintended target in the user’s filesystem.

Maintainer options:

Harden the wrapper recipe (recommended)
Add explicit PATH setup and a guard that treats both existing paths and dangling symlinks as occupied before merging.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Update `skills/codex-first/SKILL.md` so the ChatGPT app wrapper instructions ensure `~/.local/bin` is on PATH and refuse both existing paths and dangling symlinks; preserve the app-bundle-specific warning and standalone installer alternative, then run `./scripts/validate-skills` and `git diff --check`.

Next step before merge

Both remaining blockers are narrow mechanical fixes in one copy-paste shell recipe and require no product or security-policy decision.

Security
Needs attention: The copy-paste wrapper guard can follow a dangling symlink and write to an unintended local target.

Review findings

[P2] Put the wrapper directory on PATH — skills/codex-first/SKILL.md:54
[P2] Treat dangling launcher symlinks as occupied — skills/codex-first/SKILL.md:55

Review details

Best possible solution:

Keep the focused install guidance, but make the wrapper discoverable by explicitly handling PATH and make launcher creation refuse both existing files and dangling symlinks.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug classification, although the PR supplies convincing live CLI output reproducing the documented symlink failure and validating the wrapper behavior.

Is this the best way to solve the issue?

No; the exec-wrapper direction is appropriate, but the current recipe must handle PATH discovery and dangling symlinks before it is safe and effective documentation.

Full review comments:

[P2] Put the wrapper directory on PATH — skills/codex-first/SKILL.md:54
The section handles the case where codex is not on PATH, but this recipe only creates ~/.local/bin/codex; macOS does not guarantee that directory is already searchable. A fresh app-only setup can therefore complete the recipe and still fail at command codex. Add an explicit PATH step or use a guaranteed searchable location.
Confidence: 0.99
[P2] Treat dangling launcher symlinks as occupied — skills/codex-first/SKILL.md:55
[ -e ~/.local/bin/codex ] returns false for a dangling symlink, so the following redirection traverses that symlink and may create or overwrite its target. Check -L as well, or use another no-clobber creation method that refuses every existing directory entry.
Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 2de62bda0d58.

Label changes

Label changes:

add merge-risk: 🚨 other: The documented command can fail to expose Codex and can write through a dangling symlink, risks that ordinary CI does not settle.

Label justifications:

P3: This is a narrowly scoped documentation and shell-recipe correction with limited blast radius.
merge-risk: 🚨 other: The documented command can fail to expose Codex and can write through a dangling symlink, risks that ordinary CI does not settle.
rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body shows after-fix live output where the same bundled binary fails through a symlink but succeeds through the wrapper and direct invocation.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body shows after-fix live output where the same bundled binary fails through a symlink but succeeds through the wrapper and direct invocation.

Evidence reviewed

Security concerns:

[low] Dangling symlink write-through — skills/codex-first/SKILL.md:55
The existence test does not detect dangling symlinks, while the subsequent redirection follows them; users could unintentionally write outside the intended launcher path.
Confidence: 0.98

Acceptance criteria:

[P1] ./scripts/validate-skills.
[P1] git diff --check.

What I checked:

Current main lacks the guidance: Current main still only provides the fnm exec --using default -- codex fallback, so the app-bundled executable remains undocumented. (raw.githubusercontent.com) (skills/codex-first/SKILL.md:51, 2de62bda0d58)
Wrapper directory is not exposed: The recipe creates ~/.local/bin/codex but never ensures ~/.local/bin is on PATH, despite addressing machines where codex is not currently discoverable. (skills/codex-first/SKILL.md:54, 9f813ef8e307)
Dangling symlinks remain unsafe: The [ -e ~/.local/bin/codex ] guard is false for a dangling symlink, after which shell redirection follows that symlink and can write to its target. (skills/codex-first/SKILL.md:55, 9f813ef8e307)
Review continuity: The current head is the same 9f813ef8e3076450962120c50c9daf67e8b7f677 SHA reviewed in the previous cycle, so its two P2 findings remain unresolved rather than newly discovered. (skills/codex-first/SKILL.md:54, 9f813ef8e307)
Real behavior proof: The PR body provides a controlled live comparison where the same bundled binary fails through a symlink but successfully creates the test file through the exec-wrapper and direct invocation. (9f813ef8e307)
Feature history: The codex-first skill was introduced in 6ec0fc95911a76514e62793d69f9b28a23305134, and its recent model and invocation defaults were updated in 4349ce571d4cd146a47ba092f75b15386f9f8e85, both by steipete. (github.com) (skills/codex-first/SKILL.md:1, 6ec0fc95911a)

Likely related people:

steipete: Introduced the codex-first skill and made its most recent merged workflow-default update. (github.com) (role: feature owner; confidence: high; commits: 6ec0fc95911a, 4349ce571d4c; files: skills/codex-first/SKILL.md, AGENTS.MD)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (2 earlier review cycles)

reviewed 2026-07-14T10:59:54.721Z sha f55f191 :: needs real behavior proof before merge. :: [P2] Scope the no-symlink rule to the app-bundled executable | [P2] Create the wrapper directory before redirecting into it
reviewed 2026-07-16T02:53:53.657Z sha 9f813ef :: needs changes before merge. :: [P2] Put the wrapper directory on PATH | [P2] Treat dangling launcher symlinks as occupied

…afe wrapper - Narrow the no-symlink rule to the ChatGPT-app-bundled binary; package manager symlinks/shims (npm/standalone) are fine and no longer discouraged. - Make the wrapper recipe non-destructive: `mkdir -p ~/.local/bin` first and skip if a launcher already exists, so it works on a fresh app-only machine and never clobbers an existing codex. Addresses ClawSweeper P2 findings on PR steipete#29.

notorious-d-e-v · 2026-07-15T08:51:08Z

Thanks for the review — addressed both P2 findings and the P1 proof gap in a9293db:

Scoped no-symlink to the app bundle — package-manager symlinks/shims (npm/standalone) are explicitly fine now; the caveat only covers the ChatGPT.app binary.
Non-destructive wrapper — mkdir -p ~/.local/bin first, and skips if a launcher already exists (no clobber, works on a fresh app-only machine).
Behavior proof added to the PR description: isolated repro on codex-cli 0.144.0-alpha.4 where only the launcher varies — symlink → the workspace execution host is missing, exec-wrapper → ok, direct binary → ok. Same binary all three runs, so the failure is isolated to symlink invocation of the bundled binary.

@clawsweeper re-review

clawsweeper · 2026-07-15T08:51:10Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The durable review comment was published and its verdict was queued for target-serialized routing.
Run: https://github.com/openclaw/clawsweeper/actions/runs/29478314009
Updated: 2026-07-16T07:01:06.941Z

simplify

steipete · 2026-07-16T17:37:58Z

Maintainer update at b9ddd2c9bb256cdeec7b3fe4f5ad4a33e7a74068:

merged current origin/main into the contributor branch without rewriting contributor commits
added current-session PATH setup plus persistent-zsh guidance
made existing regular files and dangling symlinks explicit no-clobber cases
added changelog credit for @notorious-d-e-v

Proof:

$ scripts/validate-skills
Validated 66 skill(s).

$ git diff --check
[exit 0]

$ /Applications/ChatGPT.app/Contents/Resources/codex --version
codex-cli 0.144.2

Black-box wrapper probes in isolated temporary HOME directories:

fresh.command=/private/tmp/.../fresh/.local/bin/codex
fresh.version=codex-cli 0.144.2
regular.warning=codex launcher already exists; leaving it unchanged
regular.unchanged=yes
dangling.warning=codex launcher already exists; leaving it unchanged
dangling.symlink=yes
dangling.target-created=no

Live E2E through a temporary exec-wrapper to the app-bundled binary, using the existing signed-in context:

$ codex exec --yolo --skip-git-repo-check -m gpt-5.6-sol -c model_reasoning_effort=low --disable fast_mode 'Create ok.txt containing exactly hi and no newline.'
live.exit=0
live.file=present
live.content=hi

Autoreview: Codex gpt-5.6-sol, local mode before commit, exit 0, no accepted/actionable findings.

@clawsweeper re-review

clawsweeper · 2026-07-16T17:38:02Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

steipete · 2026-07-16T17:41:15Z

Follow-up at 2deb764: removed the unconditional claim that the bundled CLI shares the ChatGPT app's sign-in. The wrapper path itself remains live-proven.

Observable auth probe, with no credential contents read:

$ /Applications/ChatGPT.app/Contents/Resources/codex login status
Logged in using ChatGPT

$ HOME=<isolated> /Applications/ChatGPT.app/Contents/Resources/codex login status
Not logged in

$ CODEX_HOME=<isolated> /Applications/ChatGPT.app/Contents/Resources/codex login status
Not logged in

scripts/validate-skills and git diff --check pass. Final autoreview rerun: clean, no accepted/actionable findings.

@clawsweeper re-review

clawsweeper · 2026-07-16T17:41:18Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The item is closed; no stale verdict was published.
Run: https://github.com/openclaw/clawsweeper/actions/runs/29529509364
Updated: 2026-07-16T19:51:22.073Z

Update Codex usage instructions in SKILL.md

9f813ef

simplify

docs: update Codex desktop CLI guidance

b9ddd2c

docs: clarify bundled Codex authentication

2deb764

steipete merged commit fd8807d into steipete:main Jul 16, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(codex-first): cover ChatGPT-app-bundled Codex on PATH#29

docs(codex-first): cover ChatGPT-app-bundled Codex on PATH#29
steipete merged 5 commits into
steipete:mainfrom
notorious-d-e-v:fix/codex-first-chatgpt-app-merge

notorious-d-e-v commented Jul 14, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

notorious-d-e-v commented Jul 15, 2026

Uh oh!

clawsweeper Bot commented Jul 15, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 16, 2026

Uh oh!

clawsweeper Bot commented Jul 16, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 16, 2026

Uh oh!

clawsweeper Bot commented Jul 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

notorious-d-e-v commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review updates (addresses ClawSweeper findings)

Behavior proof (codex-cli 0.144.0-alpha.4, macOS)

Uh oh!

clawsweeper Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

notorious-d-e-v commented Jul 15, 2026

Uh oh!

clawsweeper Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jul 16, 2026

Uh oh!

clawsweeper Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jul 16, 2026

Uh oh!

clawsweeper Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

notorious-d-e-v commented Jul 14, 2026 •

edited

Loading

clawsweeper Bot commented Jul 14, 2026 •

edited

Loading

clawsweeper Bot commented Jul 15, 2026 •

edited

Loading

clawsweeper Bot commented Jul 16, 2026 •

edited

Loading

clawsweeper Bot commented Jul 16, 2026 •

edited

Loading