Add Codex SDK (TypeScript + Python): headless JSON event stream, programmatic control, and ChatGPT subscription authentication

[jroth55]

What feature would you like to see?

Proposal:

Introduce a Codex SDK (TypeScript and Python) that programmatically drives the existing codex CLI in a headless, JSON-event-stream mode. The SDK would expose the same tools, permissions, and MCP capabilities as the CLI, plus structured streaming for integration with IDEs, agents, CI/CD, and server apps.

Motivation:

• Make codex a first-class primitive for the community to build codex-powered agents and services, similar to how the Claude Code SDK enables wider ecosystem tooling.
• Unlock a parallel “subscription auth” path using ChatGPT subscriptions (like @ruvnet/claude-flow leverages Claude Code), alongside API-key auth.
• Enable programmatic embedding for IDEs, bots, CI/CD, agent orchestration, and enterprise governance.

Goals:

• Provide a stable SDK (TS + Python) that:
  • Spawns and controls codex CLI in headless mode
  • Streams structured JSON events (assistant messages, tool calls, permission prompts, results, usage)
  • Surfaces the same tool and permission model as CLI
  • Supports MCP configuration and project settings
  • Supports API key and ChatGPT subscription login

Design Sketch:

• SDK spawns codex CLI, streams JSON events via stdout
• Typed events: session_started, user_message, assistant_message, tool_call, tool_result, permission_request, permission_decision, usage, session_finished
• TypeScript and Python SDKs with async iterator/stream APIs
• 1:1 mapping to CLI flags/options for discoverability
• Auth tracks: API key (metered), ChatGPT subscription, enterprise cloud
• Maintains sandboxing/safety in SDK-driven sessions

Ecosystem Impact:

• Unlocks new integrations (agents, IDEs, CI, enterprise workflows)
• Enables community projects (like @ruvnet/claude-flow for Claude Code)
• Makes codex embeddable and composable for advanced use-cases

Are you interested in implementing this feature?

No

Additional information

This feature is requested by multiple community members and is a common primitive for agentic workflows. Having a codex SDK with headless JSON streaming and dual-mode authentication (API key + ChatGPT subscription) would make codex a true agent platform and close feature parity with Claude Code SDK. See also @ruvnet/claude-flow for a parallel/related community project.

[aehlke]

@tibo-openai asked me for feedback on what an API/SDK would encompass minimally, here: https://x.com/thsottiaux/status/1964749995825066275

[planger]

This proposal sounds very promising. We recently developed an IDE integration leveraging the Claude Code SDK, building a native IDE integration based on Theia IDE to showcase what a deeply integrated AI coding experience can look like (demo video).

With an SDK like the one described here, we could envision creating a similar integration for Codex in Theia — enabling a more native and deeper integration, from IDE context awareness to Codex (current diagnostics from language servers, recent edits, last terminal commands/outputs, etc.), drag and drop from file explorer into the context of a Codex session, showing changes applied by Codex within a session in a dedicated area and native diff editors, and more.

Drawing on our experience, we found the following to be very important for such an integration — partly beyond what was sketched above:

• Headless session control – not just spawning sessions, but enabling continuation from any response. This allows users to edit past messages, switch sessions in the UI, and maintain continuity. (Claude Code CLI does this by assigning a UUID to every response, which you can resume from.)
• Typed JSON event stream – including not only assistant/user messages, tool calls, and results, but especially async permission requests. These let the IDE surface dedicated UIs where users can interactively decide how to proceed (streaming input/output, permission prompts, etc.).
• Change-tracking hooks – so the IDE can track and surface Codex-proposed edits directly in a dedicated area and native diff editors, making it clear what is being changed in long-running sessions.
• System message augmentation – allowing the IDE to append additional context dynamically (e.g. open editors, recent edits, commands, project state) into the session, so Codex remains in sync with the developer’s workflow.

We’d be happy to share more details or lessons learned from our own IDE integrations if that would be useful for shaping the SDK design. Let us know if we can help (SDK or IDE integrations)! We really see this as a key enabler for the community to build reliable, interactive, and deeply native Codex-powered developer experiences.