codex-auth

name	codex-auth
description	Complete an OpenAI Codex CLI device-code sign-in by POSTing to the local codex-auth-server (default http://127.0.0.1:3334). The server drives the user's already-attached Chrome via playwright-cli to walk the OAuth flow (account chooser → consent → 9-char code → success). Use when the user pastes a "Follow these steps to sign in with ChatGPT using device code authorization" message.

codex-auth — complete a Codex device sign-in via codex-auth-server

When to use

The user provides (typically by pasting a Codex CLI message) a device auth URL like https://auth.openai.com/codex/device and a 9-char code formatted like ABCD-EFGHI. They want you to complete it in their already-running Chrome.

Prerequisite

The local codex-auth-server must be running. Verify:

curl -s http://127.0.0.1:3334/health

Expect {"ok": true}. If it doesn't respond:

• Tell the user the server isn't running and stop. Do NOT try to start it yourself unless you know its install path AND the user has asked you to set up. The server has its own playwright-cli attach setup step the user controls.

Optionally, also check the real-attach probe before submitting:

curl -s http://127.0.0.1:3334/test

{"ok": true, ...} means the browser is reachable. 503 means the playwright-cli session isn't attached — tell the user to run playwright-cli attach --cdp=<their-cdp-url> and retry.

Invocation

Pick whichever input form is convenient.

A. Pass the entire pasted block as message (server extracts URL and code via regex):

curl -s -X POST http://127.0.0.1:3334/authorize \
  -H 'Content-Type: application/json' \
  --max-time 600 \
  -d "$(jq -nR --arg msg "$PASTED" '{message:$msg}')"

B. Pass url and code separately (you've already extracted them):

curl -s -X POST http://127.0.0.1:3334/authorize \
  -H 'Content-Type: application/json' \
  --max-time 600 \
  -d '{"url":"https://auth.openai.com/codex/device","code":"ABCD-EFGHI"}'

code accepts XXXX-XXXXX form or 9 alphanumeric chars (server strips the dash and uppercases).

--max-time 600 matters: the rule-based path completes in seconds, but the server's internal AI fallback (when an unexpected page appears) can take minutes.

Response handling

• 200 {"ok": true, "log": [...]} — auth completed. Tell the user e.g. "Codex device auth completed; check your terminal — the CLI should pick up the token within a few seconds." Don't dump the full log array; it's just internal state-transition labels.

• 400 {"error": "..."} — input parse failed. Show the error and ask the user to re-paste.

• 500 {"ok": false, "error": "...", "log": [...]} or {"error": "..."} — relay the error field verbatim. Common cases:

  • not attached → run playwright-cli attach --cdp=<...> and retry. The CDP URL is in <server-dir>/config.json (cdp_url key).
  • code rejected by OpenAI → expired or mistyped; user asks Codex CLI for a new code.
  • user not logged in to ChatGPT → user logs in at chatgpt.com first.
  • <agent> fallback error: ... → the AI fallback (claude/codex) couldn't recover. Show the reason; the user may need to inspect the browser tab manually.

Don'ts

• Do not call playwright-cli directly to drive the auth flow — the server already does it (and has Claude/Codex fallback for unexpected pages). Bypassing it just duplicates logic and can race the server.
• Do not call playwright-cli close, close-all, or kill-all. The daemon is shared with other tools.
• Do not store or log the device code beyond the single curl call. It's one-shot and short-lived, but treat it like a credential.

See also

The server itself, including this skill, is in <server-dir>/skills/codex-auth/SKILL.md. The repo README documents the setup flow that produces the running server.