Skip to content
Skills Library
AI & agents · Tool integration

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.

Repository
acpkit ↗
Licence
Apache-2.0
Last repository change
30.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
2
HTML comments
0
URLs in SKILL.md
42
Deprecation

No signals detected. Repository changed on 30.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 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

  1. Start Here
  2. Quick Routing
  3. Package Boundary
  4. Do Not Confuse With
  5. Primary References
  6. Public Surface
  7. Module Guide
  8. What It Does
  9. Common Integration Pattern
  10. Common Workflows
Original SKILL.md headings · 248 lines, 1,207 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.