| name | issuing-codex-pairing-code |
| description | Issue a Codex remote-control computer pairing/authentication code only when the latest user message explicitly asks to issue or share a Codex pairing code, computer connection code, authentication code, or remote-control code. Do not use for general remote-control diagnostics, setup explanation, connection troubleshooting, or UI navigation unless code issuance is explicitly requested. |
Issue Codex Pairing Code
Use this skill to issue a Codex remote-control computer pairing code through a helper-owned temporary app-server. The skill does not pair the device itself.
Procedure
- Confirm the latest user message explicitly asks for a pairing/authentication/computer connection code.
- If the user only asks for diagnostics, setup help, or UI navigation, do not run the script. Ask a short clarification instead.
- Confirm the host is macOS/Darwin for live issuance.
- On Linux/NixOS, do not attempt live issuance. Use
--mock only for fixture validation and state that NixOS live issuance was not run.
- Run the helper from this skill directory:
python3 scripts/issue_pairing_code.py --user-requested-code
- Share only the
Code, Expires, and Cleanup lines with the user.
- Do not store raw pairing codes, raw pairing tokens, full JSON-RPC payloads, or full helper output in committed files, progress notes, PR text, or issue comments.
- If the helper reports that the local Codex app-server protocol does not expose
manualPairingCode, state that no live code was issued because the helper failed before starting app-server. The pairing API is an experimental Codex surface (the helper checks generate-ts --experimental output and opts in via capabilities.experimentalApi), so this failure means the installed Codex build dropped or renamed the pairing API.
- Leave cleanup under user control unless they ask you to clean up. Use the exact
Cleanup line printed by the helper; it includes the unique tmux session and private runtime directory for that issuance.
- After the device pairs, remote control keeps flowing through this helper-owned app-server, so the tmux session must stay alive while the user wants remote control; running the
Cleanup line also disconnects remote control.
tmux kill-session -t codex-pair-bg-...; rm -rf /private/tmp/codex-pairing-code-...
Guardrails
- Live issuance is Darwin/macOS only.
- The helper must fail before binary lookup, socket discovery, tmux spawn, or RPC on non-Darwin live runs.
- The helper must fail before socket discovery, tmux spawn, or RPC when the local Codex app-server protocol does not expose a manual pairing-code response field.
- The helper uses only a helper-owned private runtime directory and tmux session by default.
- Do not automatically discover or reuse ambient Codex app-server sockets.
- Do not use Computer Use, browser UI automation, SSH, launchd/systemd installation, persistent daemon setup, or scheduler cleanup for this flow.
- Codex has no perfect structural auto-trigger block, so the description and this explicit consent gate are both part of the safety boundary.
Validation
Use mock mode for deterministic checks:
python3 scripts/issue_pairing_code.py --mock --json
Run tests from the repo root:
python3 -m unittest discover modules/shared/programs/claude/files/skills/issuing-codex-pairing-code/tests
