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

> Find the TypeScript SDK in the openai/codex repository within the sdk/typescript directory. Access public API, client classes, and build tools for Codex services.

- Repository: [OpenAI/codex](https://github.com/openai/codex)
- Tags: api-reference
- Published: 2026-03-06

---

**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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/basic_streaming.ts) – Shows how to use `runStreamed()` to handle real-time events
- [`structured_output.ts`](https://github.com/openai/codex/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/openai/codex/blob/main/src/index.ts)) and utilize the core classes defined in [`src/codex.ts`](https://github.com/openai/codex/blob/main/src/codex.ts) and [`src/thread.ts`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/sdk/typescript/src/index.ts), which exports the `Codex` client and `Thread` management classes.
- Core implementation files include [`codex.ts`](https://github.com/openai/codex/blob/main/codex.ts) (client), [`codexOptions.ts`](https://github.com/openai/codex/blob/main/codexOptions.ts) (configuration), [`thread.ts`](https://github.com/openai/codex/blob/main/thread.ts) (conversation management), and [`events.ts`](https://github.com/openai/codex/blob/main/events.ts) (streaming types).
- The SDK is built using **tsup** via [`sdk/typescript/tsup.config.ts`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/sdk/typescript/src/events.ts), such as `turnStarted`, `itemUpdated`, and `turnCompleted`, allowing real-time processing of Codex responses.