codex-telegram-bot/.codex/skills/codex-app-server-upgrade/SKILL.md

name, description

name	description
codex-app-server-upgrade	Safely check, update, or self-upgrade the host Codex app-server, Codex CLI binary, and its code-mode host for this project. Use when asked to upgrade Codex, repair or update its code-mode host, run app-server update checks, restart Codex after an update, or let Codex invoke its own app-server upgrade through the project script.

Codex App Server Upgrade

Use the project app-server script instead of manually replacing binaries. It is designed to be portable and self-upgrade-safe.

Locate the Script

Work from the current project root when possible. The script is:

scripts/start-codex-app-server

If the current directory is not the project root, find the nearest repository containing scripts/start-codex-app-server and run commands from that directory. Do not hardcode absolute paths.

Commands

Start with automatic approval review when needed:

scripts/start-codex-app-server start --approve-for-me

For a durable setting across restarts and upgrades, set CODEX_APPROVE_FOR_ME=1 in .env.

Check status:

scripts/start-codex-app-server status

Check for updates without changing anything:

scripts/start-codex-app-server check-updates

Apply an upgrade non-interactively:

scripts/start-codex-app-server check-updates -y

check-upgrade is accepted as an alias for check-updates.

Self-Upgrade Behavior

When the app-server is running, check-updates -y downloads and validates matching Codex, code-mode host, and Linux bwrap binaries from the same release first. It then starts a detached worker to stop the app-server process group, replace all downloaded components, and start the app-server again. Release archives may contain target-suffixed executable names; the installer normalizes them to their stable installed paths.

If Codex is already current but its sibling codex-code-mode-host binary is missing, check-updates downloads and installs the checked companion binary. On Linux it also repairs the bundled bwrap helper when needed.

Expect the current Codex connection or tool call to be interrupted after the handoff. After a short delay, verify the outcome with:

scripts/start-codex-app-server status

If needed, inspect the portable project-local upgrade log:

sed -n '1,160p' run/codex-app-server-upgrade.log

Safety Rules

• Do not manually kill, mv, or overwrite the Codex or code-mode host binaries for this workflow.
• Do not assume /usr/local/bin/codex, a specific home directory, or any machine-specific path.
• Use CODEX_BIN=/absolute/path/to/codex only when the user or environment explicitly requires a non-default binary.
• If the script reports that it cannot replace the binary without write permission, stop and report that non-interactive privileges or a writable CODEX_BIN are required.
• Do not run check-updates -y unless the user explicitly asked to upgrade or auto-approve the update.