codex-auth-helper
/codex-auth-helper
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.
- Author
- vcoderun ↗
- Repository
- acpkit ↗
- Licence
- Apache-2.0
- Last repository change
- 30.09.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 42
No signals detected. Repository changed on 30.09.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: examples/codex_chat_openai_graph.py, examples/codex_responses_agent.py
What it does and when to use it
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.
Original author 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.
How it works
- Start Here
- Quick Routing
- Package Boundary
- Do Not Confuse With
- Primary References
- Public Surface
- Module Guide
- What It Does
- Common Integration Pattern
- Common Workflows
SKILL.md preview
--- 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](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py) for public constructor behavior 3. open the [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py) for refresh logic 4. open the [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) and the [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py) 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](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py), [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py) | | token refresh timing or refresh requests | Yes | [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py), [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py) | | Codex-specific request headers or account id | Yes | [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py), [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) | | building a `CodexResponsesModel` | Yes | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py) | | building a LangChain `ChatOpenAI` | Yes | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | | exposing that model through ACP | Pair with `pydantic-acp` | [Pydantic adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/pydantic-acp) | | exposing a Codex-backed LangChain graph through ACP | Pair with `langchain-acp` | [LangChain adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/langchain-acp) | | outbound Codex Responses WebSocket | Yes, Pydantic and async LangChain | [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py), [LangChain module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/langchain.py), [WebSocket module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/_responses_websocket.py) | | exposing an ACP runtime over WebSocket | No, pair with `acpremote` | [remote transport package](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) | ## Package Boundary This package is not: - an ACP adapter - a CLI package - an ACP 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 - optional outbound Responses connection/session ownership ## 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 can select the model's outbound Responses connection; it does not expose an ACP runtime over a remote transport It does not own: - ACP session lifecycle - approvals - ACP transport - CLI dispatch ## Primary References Package references: - [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/codex-auth-helper/SKILL.md) - [Raw helpers docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/helpers.md) - [Raw API docs page](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/api/codex_auth_helper.md) - [Rendered helper docs](https://vcoderun.github.io/acpkit/helpers/) - [Source tree](https://github.com/vcoderun/acpkit/tree/main/packages/helpers/codex-auth-helper) Cross-skill reference: - [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md) ## Public Surface High-value public seams: - `create_codex_responses_model(...)` - `create_codex_async_openai(...)` - `create_codex_openai(...)` - `create_codex_chat_openai(...)` - `CodexAsyncOpenAI` - `CodexOpenAI` - `CodexResponsesModel` - `CodexResponsesConnection` - `CodexResponsesFallback` - `CodexResponsesSessionInfo` - `CodexResponsesConnectionError` - `CodexResponsesProtocolError` - `CodexResponsesTransportEvent` - `CodexResponsesTransportObserver` - `CodexAuthConfig` - `CodexAuthState` - `CodexAuthStore` - `CodexTokenManager` Package entrypoint: - [Package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/__init__.py) ## Module Guide | Subsystem | Key files | Use them for | | --- | --- | --- | | top-level constructors and model surface | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | building public client/model objects and default request behavior | | Responses WebSocket | [WebSocket module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/_responses_websocket.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | outbound connection lifecycle, event mapping, and continuation safety | | auth state and persistence | [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py), [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py), [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py) | parsing auth payloads, persistence, path config | | token refresh | [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py) | 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 - optionally keeps one outbound Responses WebSocket for a Pydantic logical run It does not: - perform `codex login` - create a login session from nothing - support unrelated OpenAI Chat Completions flows - adapt a runtime to ACP - expose an ACP runtime 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=...`. Use `Agent.run_stream(...)` when the caller needs incremental text; `CodexResponsesModel` forwards Responses API deltas as they arrive instead of buffering the completed response. ### Build a lower-level client first Use `create_codex_async_openai(...)` when you need the transport/client object explicitly. ### Keep one Responses connection for a Pydantic run Install the `websocket` extra, pass `connection="websocket"`, and wrap the whole async agent run in `model.responses_session()`. Keep strict fallback for measurements. Non-streaming responses recover transient failures with bounded reconnects; opt-in HTTP fallback follows exhaustion. Exposed streams are not replayed. ### 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. WebSocket factories leave stream selection automatic: ordinary `ainvoke` buffers the response for recovery and `astream` receives live chunks. Explicit streaming settings/callbacks can bypass response recovery. HTTP factories retain their `streaming=True` default. ### Debug refresh behavior Start from the [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py), then inspect the [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) and the [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py). ## Skill-Bundled Example Skill-local example: - [Codex-backed agent example](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/codex_responses_agent.py) - [Codex-backed LangChain graph example](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/codex_chat_openai_graph.py) - [Example notes](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/README.md) 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. - Keep `request()` and `request_stream()` distinct: `request()` may collect a required SSE response, while `request_stream()` must expose deltas before the terminal response event. - Keep HTTP as the default; WebSocket continuation must be explicitly selected and scoped to one logical run. - Treat local Codex auth as machine-local user state; do not bake it into images, artifacts, CI logs, or shared volumes.
Files in this package (5)
- SKILL.md 13 KB
- agents/openai.yaml 1 KB
- examples/README.md 1 KB
- examples/codex_chat_openai_graph.py 1 KB
- examples/codex_responses_agent.py 1 KB
Versions
The database has no other skills named codex-auth-helper.
Database snapshot: 13.11.2026 · package version 011138595890 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95pydantic-acp
Use for `pydantic-acp` tasks: exposing `pydantic_ai.Agent` through ACP, adapter config/runtime ownership, extension routing, authentication, prompt capabilities, slash commands, approvals, plans, hooks, projections, host-backed tools, and Pydantic-specific examples. - 100langchain-acp
Use for `langchain-acp` tasks: exposing LangChain, LangGraph, and DeepAgents graphs through ACP, graph/session construction, plans, bridges, projections, and LangChain-specific examples. - 100migrating-deep-agents-to-pydantic-ai-harness
Migrate Python LangChain Deep Agents applications to Pydantic AI and Pydantic AI Harness. Use when the source uses the upstream `deepagents` package or demonstrably reproduces its middleware, backends, skills, memory, subagents, or sandbox contracts. Use… - 100migrating-langchain-to-pydantic-ai
Migrate Python LangChain, LangGraph, or Deep Agents applications to Pydantic AI and, when the source uses harness features, Pydantic AI Harness. Use for LangChain agents, chains, LCEL, direct LangGraph graphs, persistence, interrupts, streaming, and `create_deep_agent` projects… - 100acp-service
使用 @1agents/acp-service 管理 ACP 会话与 DSH 插件,通过 A2A 调用固定角色、派发临时任务、查询父子任务和执行轮次、记录业务验收及处理通知,并回投 Codex/DSH 原会话。也用于项目/角色候选探查、目标登记、网络技能缓存和更新接口接入;不用于无关的系统巡检或模型配置。 - 100pydanticai-docs
Use this skill whenever the user is working with the Pydantic AI framework — including building AI agents, defining structured outputs with Pydantic models, wiring up tools/function calling, configuring model providers (OpenAI, Anthropic, Gemini, etc.), managing dependencies via…