NPM OpenAI Codex Client

⚠️ EXPERIMENTAL & UNOFFICIAL ⚠️

This is an experimental, unofficial TypeScript client for the OpenAI Codex API with built-in authentication, tool support, and streaming responses.

Important Disclaimers:

• This project is not affiliated with or endorsed by OpenAI
• This is a reverse-engineered implementation and may break at any time
• Use at your own risk - this is for educational and experimental purposes only
• The API endpoints and authentication methods may change without notice

Installation

npm install @wkronmiller/openai-codex-client

Usage

Basic Usage

import { OpenAiCodexClient } from '@wkronmiller/openai-codex-client';

// Create a client instance
const client = await OpenAiCodexClient.create();

// Create a streaming response
const stream = await client.responses.create({
  input: [{
    type: 'message',
    role: 'user',
    content: [{
      type: 'input_text',
      text: 'Hello, how can you help me with code analysis?'
    }]
  }]
});

// Process the streaming response
for await (const chunk of stream) {
  console.log(chunk);
}

Using Individual Components

import { 
  loadAuthFile, 
  createOpenAIClient, 
  PlanTool, 
  ShellTool 
} from '@wkronmiller/openai-codex-client';

// Load authentication
const authInfo = await loadAuthFile();

// Create OpenAI client
const openaiClient = createOpenAIClient(authInfo);

// Access tools
console.log('Available tools:', PlanTool, ShellTool);

API Reference

OpenAiCodexClient

The main client class for interacting with the OpenAI Codex API.

Methods

• static create(): Promise<OpenAiCodexClient>

  • Creates a new client instance
  • Automatically loads authentication from the system
  • Uses predefined instructions from the OpenAI Codex repository

• responses.create(params: { input: ResponseInput }): Promise<Stream>

  • Creates a streaming response with the configured model and tools
  • Uses GPT-5 model with PlanTool and ShellTool enabled

Authentication

The client automatically handles authentication by loading credentials from the system. Make sure you have valid OpenAI Codex API credentials configured.

The application expects an authentication file at ~/.codex/auth.json with the following structure:

• OpenAI API key
• JWT tokens (id_token, access_token, refresh_token)
• Account information

Run codex login to set up authentication before using the application.

Tools

The client comes with two built-in tools:

• PlanTool: For planning and organizing tasks
• ShellTool: For executing shell commands and system operations

Development

Project Structure

src/
├── auth/
│   ├── auth-service.ts     # Authentication and token management
│   ├── auth-service.test.ts # Authentication tests
│   └── index.ts           # Auth module exports
├── client/
│   ├── openai-client.ts    # OpenAI client configuration
│   ├── openai-client.integration.test.ts # Integration tests
│   └── index.ts           # Client module exports
├── tools/
│   ├── tool-definitions.ts # Tool definitions for the API
│   └── index.ts           # Tools module exports
├── types/
│   ├── auth.ts            # Authentication-related interfaces
│   ├── tools.ts           # Tool-related interfaces
│   └── index.ts           # Types module exports
└── index.ts               # Main application entry point

Building

npm run build

Development

bun run dev

Testing

# Run all tests
npm test

# Run integration tests
npm run test:integration

Requirements

• Node.js 18+ or Bun
• TypeScript 5+
• Valid OpenAI Codex API credentials

License

Apache-2.0