| name | codex-app-server |
| description | Use when designing or implementing product integrations that embed Codex App Server, custom Codex clients, rich Codex threads, streamed agent events, approvals, auth, skills, or app connector flows. |
Codex App Server
Use this skill before proposing or building Codex App Server integrations. Ground decisions in the current OpenAI docs, then adapt the experience to the product.
Sources checked: OpenAI Codex App Server docs, Codex SDK docs, Codex open-source docs, and Codex use-case docs on 2026-05-16.
Fit Check
- Use
codex app-server for rich product clients that need embedded Codex conversations, auth, conversation history, approvals, and streamed agent events.
- Use the Codex SDK instead for automation jobs, CI, or non-interactive task runners.
- Treat the protocol as versioned by the local Codex binary. Generate schemas from the installed CLI before implementing typed clients:
codex app-server generate-ts --out ./schemascodex app-server generate-json-schema --out ./schemas
Protocol Basics
- App Server uses JSON-RPC 2.0 style messages over:
stdio, the default, as newline-delimited JSON.websocket, experimental and unsupported.off, when no local transport should be exposed.
- After opening a connection, send
initialize with client metadata, then send the initialized notification before any other request.
- Start with
thread/start, continue with thread/resume, branch with thread/fork, and begin work with turn/start.
- After
turn/start, keep reading notifications such as item/started, item/completed, item/agentMessage/delta, tool progress, and thread archive state.
- Use
turn/steer only to append user input to an active turn.
Security Defaults
- Prefer
stdio for local embedded clients unless there is a concrete WebSocket need.
- If using WebSocket, bind to loopback for local flows. Non-loopback WebSocket listeners can allow unauthenticated connections by default during rollout; configure WebSocket auth before exposing remotely.
- Prefer
--ws-token-file over command-line raw tokens. Use --ws-token-sha256 only when the raw high-entropy token lives in a separate local secret store.
- Handle WebSocket overload error
-32001 with exponential backoff and jitter.
- Keep approval UX explicit. App Server can request command execution approvals, file change approvals, network approvals, user input, dynamic tool calls, and app connector approvals.
Auth And Apps
- Use
account/read to check auth state.
- App Server supports API key login, ChatGPT browser login, ChatGPT device-code login, logout, and experimental externally managed ChatGPT tokens.
- Use
app/list to fetch accessible and enabled app connectors. It returns access/install state separately from local enablement state.
- When passing a connector into a turn, include both the text marker and a
mention input item such as app://demo-app.
- Use
skills/list to fetch available skills for one or more cwd values. Include a skill input item when invoking a skill to avoid extra lookup latency.
Matchday Integration Guardrails
- Do not use Codex App Server to bypass this app's server-side auth or authorization. Merchant actions still need server checks.
- Keep match outcomes, final whistle timing, teams, and fixtures local and deterministic unless the user explicitly asks for a research-only surface.
- Treat Codex outputs as recommendations, drafts, or explainable research until a merchant approves a campaign or content change.
- For fan-facing features, make the Codex presence thematic and constrained: rivalry research, promotion drafts, fixture-aware merch copy, or campaign QA. Avoid presenting generated claims as official tournament facts unless grounded in local data or cited research.
Official References
