codex-auth-helper

name	codex-auth-helper
description	Use for `codex-auth-helper` tasks: reading local Codex auth state, refreshing tokens, building Codex-backed Responses clients/models, and wiring them into `pydantic-ai`, `pydantic-acp`, or LangChain.

codex-auth-helper Skill

Use this skill when the task is centered on the codex-auth-helper package.

This package exists so the repo does not re-implement Codex auth and Responses wiring ad hoc in examples, adapters, or one-off scripts.

It is intentionally narrow:

• read existing Codex auth state
• refresh tokens when needed
• derive account-scoped request headers
• build a Codex-specific async OpenAI client
• build a pydantic-ai Responses model on top of that client
• build a LangChain ChatOpenAI model on top of the same auth/session flow

Start Here

If you only need the shortest high-signal path:

1. read Quick Routing
2. open the factory module for public constructor behavior
3. open the token manager for refresh logic
4. open the auth-state module and the auth-store module for auth payload shape and persistence

Quick Routing

If the task is about...	Use this skill?	Open first
~/.codex/auth.json parsing	Yes	auth-state module, auth-store module
token refresh timing or refresh requests	Yes	token manager, auth-config module
Codex-specific request headers or account id	Yes	Codex client module, auth-state module
building a CodexResponsesModel	Yes	factory module, model module
building a LangChain ChatOpenAI	Yes	factory module, Codex client module
exposing that model through ACP	Pair with pydantic-acp	Pydantic adapter package
exposing a Codex-backed LangChain graph through ACP	Pair with langchain-acp	LangChain adapter package
WebSocket transport	No, pair with acpremote	remote transport package

Package Boundary

This package is not:

• an ACP adapter
• a CLI package
• a transport package

It is a helper for turning a local Codex login into a reusable pydantic-ai Responses model.

That means it owns:

• auth file parsing
• token refresh timing
• account-id extraction
• Codex request header shaping
• Responses-model construction

Do Not Confuse With

• codex-auth-helper vs pydantic-acp this package builds the model/client; pydantic-acp exposes the runtime through ACP
• codex-auth-helper vs acpkit-sdk this package has no CLI target-loading role
• codex-auth-helper vs acpremote this package has no transport role

It does not own:

• ACP session lifecycle
• approvals
• transport
• CLI dispatch

Primary References

Package references:

• Raw skill
• Raw helpers docs
• Raw API docs page
• Rendered helper docs
• Source tree

Cross-skill reference:

• Pydantic adapter skill

Public Surface

High-value public seams:

• create_codex_responses_model(...)
• create_codex_async_openai(...)
• create_codex_openai(...)
• create_codex_chat_openai(...)
• CodexAsyncOpenAI
• CodexOpenAI
• CodexResponsesModel
• CodexAuthConfig
• CodexAuthState
• CodexAuthStore
• CodexTokenManager

Package entrypoint:

• Package entrypoint

Module Guide

Subsystem	Key files	Use them for
top-level constructors and model surface	factory module, model module, Codex client module	building public client/model objects and default request behavior
auth state and persistence	auth-state module, auth-store module, auth-config module	parsing auth payloads, persistence, path config
token refresh	token manager	deciding whether refresh is needed and performing refresh

What It Does

It:

• reads an existing Codex auth file
• refreshes tokens when needed
• derives ChatGPT-Account-Id
• builds a Codex-specific Responses client
• returns a pydantic-ai model configured for Codex usage
• returns a LangChain ChatOpenAI configured for the Responses API

It does not:

• perform codex login
• create a login session from nothing
• support unrelated OpenAI Chat Completions flows
• adapt a runtime to ACP
• expose anything over WebSocket

Common Integration Pattern

The most important package combinations are:

• codex-auth-helper + pydantic-acp
• codex-auth-helper + langchain-acp

Normal flow:

1. call create_codex_responses_model(...)
2. construct a pydantic_ai.Agent
3. expose that agent through pydantic-acp

This helper is usually upstream of the adapter, not a replacement for it.

Common Workflows

Build a Codex-backed pydantic-ai model

Use create_codex_responses_model(...) and pass explicit instructions=....

Build a lower-level client first

Use create_codex_async_openai(...) when you need the transport/client object explicitly.

Build a LangChain model

Use create_codex_chat_openai(...) when the upstream runtime is LangChain or LangGraph and you want the Responses API path instead of hand-wiring langchain-openai. Pass explicit instructions=... here too.

Debug refresh behavior

Start from the token manager, then inspect the auth-state module and the auth-config module.

Skill-Bundled Example

Skill-local example:

• Codex-backed agent example
• Codex-backed LangChain graph example
• Example notes

This example demonstrates:

• creating the Codex-backed model
• constructing a Pydantic agent
• exposing that agent through pydantic-acp
• constructing a LangChain graph with ChatOpenAI

Handoff Rules

Pair or switch to:

• pydantic-acp when the Codex-backed model is being exposed through ACP
• langchain-acp when the Codex-backed LangChain graph is being exposed through ACP
• acpkit-sdk only when that Pydantic agent is invoked through acpkit run ... or acpkit serve ...

Stay in this skill when the main issue is:

• auth parsing
• refresh behavior
• client header behavior
• model construction

Guardrails

• Do not call this package an adapter.
• Do not claim it supports generic Chat Completions if it does not.
• Do not describe auth refresh logic that is not present in the package source.
• If the task shifts into ACP adapter runtime behavior, move to pydantic-acp.

Production Baseline

• Require explicit instructions= for Codex-backed Pydantic AI and LangChain factories.
• Never log access tokens, refresh tokens, account ids, or the contents of auth.json.
• Keep auth-file replacement atomic and private, and serialize sync and async refreshes that share one auth store.
• Preserve the enforced Responses settings, including disabled server-side storage and streaming behavior.
• Treat local Codex auth as machine-local user state; do not bake it into images, artifacts, CI logs, or shared volumes.