name	launch-codex-unpacked
description	Launch unpacked Codex Desktop builds with debug ports and optional SSH host autostart using launch_codex_unpacked.sh. Use when asked to run Codex from extracted app.asar, enable inspect/remote-debugging, select an SSH host on startup, or keep temporary unpacked artifacts for investigation.

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.

name	launch-codex-unpacked
description	Launch unpacked Codex Desktop builds with debug ports and optional SSH host autostart using launch_codex_unpacked.sh. Use when asked to run Codex from extracted app.asar, enable inspect/remote-debugging, select an SSH host on startup, or keep temporary unpacked artifacts for investigation.