launch-codex-unpacked

Launch Codex Unpacked

Use this skill when the task is to run Codex Desktop from unpacked app.asar with controlled debug settings.

Primary Script

• ./launch_codex_unpacked.sh

Preflight

Run these checks before launch:

test -x ./launch_codex_unpacked.sh
test -d /Applications/Codex.app

Tooling note:

• The launcher auto-installs missing node/npx via Homebrew by default.
• Set AUTO_INSTALL_TOOLS=0 to disable auto-install behavior.

If a custom app path is provided, verify it contains:

• <APP_PATH>/Contents/Resources/app.asar
• <APP_PATH>/Contents/Resources/codex

Common Launch Recipes

Default launch (inspect + remote debugging enabled):

./launch_codex_unpacked.sh

Custom ports:

./launch_codex_unpacked.sh --inspect-port 9330 --remote-debug-port 9333

Disable one or both debug channels:

./launch_codex_unpacked.sh --no-inspect
./launch_codex_unpacked.sh --no-remote-debug

Launch against a different Codex.app:

./launch_codex_unpacked.sh --app "/Applications/Codex.app"

Preserve extracted temp app for analysis:

./launch_codex_unpacked.sh --keep-temp

Use a fixed Chromium profile/user data directory:

./launch_codex_unpacked.sh --user-data-dir "/tmp/codex-user-data"

SSH host autostart mode:

./launch_codex_unpacked.sh --ssh-host "user@host"

What SSH mode does:

• Performs non-interactive SSH preflight (BatchMode + timeout).
• Updates ~/.codex/.codex-global-state.json (electron-ssh-hosts).
• Patches unpacked main bundle so startup opens the first saved SSH host.

Argument Pass-through

Append app arguments after --:

./launch_codex_unpacked.sh -- --some-codex-flag value

Output You Should Report

After launch, report:

• App dir path
• User data dir path
• final Command line
• whether SSH host mode was enabled

Troubleshooting

• Missing app.asar or Missing codex binary: wrong --app path.
• SSH autostart patch anchor not found: Codex bundle changed; script patch target must be updated.
• SSH preflight warning: app can still launch, but remote host connection may fail in UI.