Where Is the TypeScript SDK Located in the OpenAI Codex Repository?

The TypeScript SDK is located in the sdk/typescript directory of the openai/codex repository and contains the public API, client classes, configuration types, and build tools needed to interact with Codex services.

The openai/codex repository is organized as a monorepo containing multiple components for the Codex CLI and various language SDKs. If you are looking to integrate Codex functionality into your TypeScript or JavaScript applications, you will need to locate the TypeScript SDK within this repository. The SDK provides type-safe access to the Codex API, including client initialization, thread management, and real-time streaming capabilities.

TypeScript SDK Directory Location

The TypeScript SDK resides in the sdk/typescript directory at the root of the openai/codex repository. This directory is self-contained and includes all source files, build configuration, tests, and sample programs required to develop and distribute the SDK.

Key subdirectories within sdk/typescript include:

• src/ – Core TypeScript source files implementing the client and API
• samples/ – Ready-to-run example programs demonstrating SDK usage
• Configuration files for the build system (tsup)

Core Source Files in the TypeScript SDK

The src/ directory contains the implementation of the public API and internal utilities. Understanding these files helps you navigate the SDK's architecture and import the correct modules for your use case.

sdk/typescript/src/index.ts

The index.ts file serves as the main entry point for the TypeScript SDK. It re-exports the public types and classes, including Codex, Thread, and option types. When you import from @openai/codex, you are importing from this file.

sdk/typescript/src/codex.ts

The codex.ts file implements the Codex client class, which is the primary interface for communicating with the Codex app-server. This class handles authentication, request routing, and connection management. You instantiate this class with your API key and optional configuration parameters.

sdk/typescript/src/codexOptions.ts

The codexOptions.ts file defines the configuration schema for the client, including the API URL, authentication tokens, sandbox mode settings, and other runtime options. These types ensure type safety when initializing the Codex client.

sdk/typescript/src/thread.ts

The thread.ts file provides the Thread class, a high-level wrapper that manages a Codex conversation thread. It exposes methods such as run() for synchronous execution and runStreamed() for streaming responses. This class abstracts the complexity of managing conversation state and event handling.

sdk/typescript/src/exec.ts

The exec.ts file contains low-level "exec" helpers used by CodexExec for direct command execution. This utility supports the SDK's ability to execute commands within sandboxed environments.

sdk/typescript/src/events.ts

The events.ts file defines TypeScript type definitions for the event stream emitted by the server. These types include turnStarted, itemUpdated, and turnCompleted, which are essential for handling streaming responses in your applications.

Build Configuration and Sample Programs

The TypeScript SDK includes build tooling and example code to help you get started quickly.

Build System

The SDK is built using tsup, a modern TypeScript bundler. The configuration file sdk/typescript/tsup.config.ts defines the entry points, output formats (ESM and CJS), and bundling options. This ensures the SDK is compatible with both modern ES modules and CommonJS environments.

Sample Programs

The sdk/typescript/samples directory contains ready-to-run examples demonstrating various SDK capabilities:

• basic_streaming.ts – Shows how to use runStreamed() to handle real-time events
• structured_output.ts – Demonstrates structured output parsing with Zod schemas

These samples provide practical starting points for implementing the SDK in your own projects.

How to Use the TypeScript SDK

To use the TypeScript SDK in your project, install the package and import the Codex and Thread classes from the main entry point.

Basic Usage

The following example demonstrates creating a client, initializing a thread, and running a simple prompt:

import { Codex, Thread } from "@openai/codex";

async function main() {
  const codex = new Codex({
    apiKey: process.env.CODEX_API_KEY!,
    // Optional: override endpoint, sandbox mode, etc.
  });

  const thread = new Thread(codex);
  const result = await thread.run("Write a short poem about autumn.");
  console.log(result);
}

main().catch(console.error);

Streaming Responses

For real-time interaction, use the runStreamed() method to process events as they arrive from the server:

import { Codex, Thread } from "@openai/codex";

async function streamDemo() {
  const codex = new Codex({ apiKey: process.env.CODEX_API_KEY! });
  const thread = new Thread(codex);

  const stream = thread.runStreamed("Explain the difference between async/await and promises.");
  for await (const event of stream) {
    if (event.type === "turnStarted") {
      console.log("Turn started");
    } else if (event.type === "itemUpdated") {
      console.log(`Item ${event.item.id} updated:`, event.item);
    } else if (event.type === "turnCompleted") {
      console.log("Turn finished, result:", event.result);
    }
  }
}

streamDemo().catch(console.error);

These examples import from the main entry point (src/index.ts) and utilize the core classes defined in src/codex.ts and src/thread.ts.

Summary

• The TypeScript SDK is located in the sdk/typescript directory of the openai/codex repository.
• The main entry point is sdk/typescript/src/index.ts, which exports the Codex client and Thread management classes.
• Core implementation files include codex.ts (client), codexOptions.ts (configuration), thread.ts (conversation management), and events.ts (streaming types).
• The SDK is built using tsup via sdk/typescript/tsup.config.ts and includes sample programs in the samples directory.

Frequently Asked Questions

Where is the TypeScript SDK located in the Codex repository?

The TypeScript SDK is located in the sdk/typescript directory at the root of the openai/codex repository. This directory contains all source code, build configuration, and sample programs for the SDK.

What is the main entry point for the TypeScript SDK?

The main entry point is sdk/typescript/src/index.ts. This file re-exports the public API, including the Codex client class, Thread management class, and all configuration types. When you import from @openai/codex, you are importing from this file.

How is the TypeScript SDK built?

The SDK is built using tsup, a modern TypeScript bundler. The build configuration is defined in sdk/typescript/tsup.config.ts, which specifies entry points, output formats for both ESM and CommonJS, and bundling options. This ensures compatibility across different module systems.

Does the TypeScript SDK support streaming responses?

Yes, the TypeScript SDK supports streaming responses through the runStreamed() method available on the Thread class. This method returns an async iterator that yields events defined in sdk/typescript/src/events.ts, such as turnStarted, itemUpdated, and turnCompleted, allowing real-time processing of Codex responses.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}