codex-app-server-sdk

codex-app-server-sdk is a standalone TypeScript extraction of the Codex app-server client that currently lives inside OpenClaw. It provides:

• a typed JSON-RPC client for codex app-server
• a process transport that spawns the app server for you
• generated protocol types for the v1 and v2 request/notification surface

Install

This repository is set up as a normal Node ESM package:

pnpm install
pnpm build

To consume it from another local project before publishing:

pnpm add /Users/kevinlin/code/codex-sdk-ts

Usage

Spawn the Codex app server

import { CodexAppServerClient } from "codex-app-server-sdk";

const client = await CodexAppServerClient.spawn({
  bin: "codex",
  cwd: process.cwd(),
});

await client.initializeSession();

const threads = await client.listThreads({
  cursor: null,
  limit: 20,
});

console.log(threads.data);

await client.close();

Start a turn and wait for completion

import { CodexAppServerClient } from "codex-app-server-sdk";
import type { TurnStartParams } from "codex-app-server-sdk/generated/protocol/v2/TurnStartParams";

const client = await CodexAppServerClient.spawn();
await client.initializeSession();

const params: TurnStartParams = {
  threadId: "thread_123",
  input: [
    {
      type: "text",
      text: "Summarize the latest changes in this repo.",
      text_elements: [],
    },
  ],
};

const { start, completed } = await client.runTurn(params, {
  timeoutMs: 60_000,
});

console.log(start.turn.id, completed.status);

await client.close();

Handle server requests

import { CodexAppServerClient } from "codex-app-server-sdk";

const client = await CodexAppServerClient.spawn();

client.handleChatgptAuthTokensRefresh(async ({ previousAccountId }) => {
  console.log("refresh requested for", previousAccountId);

  return {
    accessToken: process.env.CHATGPT_ACCESS_TOKEN!,
    chatgptAccountId: process.env.CHATGPT_ACCOUNT_ID!,
    chatgptPlanType: "plus",
  };
});

Public API

• Root entrypoint: codex-app-server-sdk
• Deep imports for generated types: codex-app-server-sdk/generated/...
• Deep imports for transport helpers: codex-app-server-sdk/transport/...

The root module exports CodexAppServerClient, CodexAppServerProcessTransport, JSON-RPC helpers, protocol helper types, and a protocol namespace for the generated base protocol index.

Development

pnpm typecheck
pnpm test
pnpm build

Notes

• The generated protocol tree was copied from the OpenClaw repository snapshot in extensions/openai/chatgpt-apps/codex-sdk.
• This package currently preserves the existing generated files as checked-in source rather than regenerating them locally.