@jxstjh/codex-app-server-sdk

TypeScript SDK for Codex App-Server with full interactive support, including approval handling and bidirectional communication.

Current status: this package has moved past the prototype stage into a usable SDK skeleton with typed session APIs, lifecycle controls, errors/retry, and a growing examples system. Start with Getting Started and the examples map. The target architecture and staged implementation plan live in ARCHITECTURE.md, and runtime distribution decisions are collected in RUNTIME_PACKAGING.md.

Features

• ✅ Full JSON-RPC 2.0 support - Bidirectional communication with app-server
• ✅ Approval handling - Typed approval hooks for commands, file changes, permissions, user input, and MCP elicitation
• ✅ Type-safe - Complete TypeScript type definitions
• ✅ Event-driven - Subscribe to thread events in real-time
• ✅ Modern ESM - Native ES modules support

Installation

npm install @jxstjh/codex-app-server-sdk
# or
pnpm add @jxstjh/codex-app-server-sdk
# or
yarn add @jxstjh/codex-app-server-sdk

Quick Start

Basic Usage

import { Codex } from "@jxstjh/codex-app-server-sdk";

const codex = await Codex.create({
  baseUrl: process.env.CODEX_BASE_URL,
  apiKey: process.env.OPENAI_API_KEY,
  codexBin: process.env.CODEX_EXECUTABLE,
  cwd: process.cwd(),
});

const thread = await codex.threadStart({
  model: "gpt-5.4",
  sandbox: "workspace-write",
  approvalPolicy: "on-failure",
});

const result = await thread.run("Hello, Codex! Create a simple web app.");
console.log(result.finalAgentMessageText);

codex.close();

Cloud / WebSocket Usage

import { Codex } from "@jxstjh/codex-app-server-sdk";

const codex = await Codex.create({
  remoteUrl: process.env.CODEX_REMOTE_URL!,
  remoteAuthToken: process.env.CODEX_REMOTE_AUTH_TOKEN!,
});

Cloud config connects to an already-running app-server and does not accept local launch fields such as codexBin, launchArgs, baseUrl, configOverrides, cwd, or env.

Typed Approval Hooks

import { Codex } from "@jxstjh/codex-app-server-sdk";
import type { ApprovalHooks } from "@jxstjh/codex-app-server-sdk";

const approvalHooks: ApprovalHooks = {
  onCommandApproval: async (params) => {
    if ((params.command ?? "").startsWith("rg ")) {
      return { decision: "accept" };
    }
    return { decision: "decline" };
  },
  onFileChangeApproval: async () => ({ decision: "accept" }),
  onUserInputRequest: async () => ({ answers: {} }),
  onUnknownRequest: async () => ({}),
};

const codex = await Codex.create({}, approvalHooks);

For low-level compatibility, the older raw ApprovalHandler shape is still supported, but typed hooks are the recommended public surface.

More docs:

• Getting Started
• API Reference
• FAQ

Event Handling

import { Codex } from "@jxstjh/codex-app-server-sdk";

const codex = await Codex.create();
const thread = await codex.threadStart();

// Subscribe to events
thread.onEvent((event) => {
  switch (event.method) {
    case "turn/started":
      console.log("Turn started:", event.threadId);
      break;
    case "turn/completed":
      console.log("Turn completed:", event.threadId);
      break;
    case "item/completed":
      console.log("Item completed:", event.data);
      break;
  }
});

await thread.run("List all files in the current directory");

API Reference

Codex

Main entry point for the SDK.

Constructor / Factory

new Codex(config?: AppServerConfig, approval?: ApprovalProvider)
Codex.create(config?: AppServerConfig, approval?: ApprovalProvider)

Parameters:

• config - App-Server configuration
  • transport - stdio for a local app-server process or websocket for a remote app-server; remoteUrl implies websocket
  • remoteUrl - Remote app-server websocket endpoint; host:port, ws://..., and wss://... are accepted
  • remoteAuthToken - Bearer token for the websocket handshake
  • codexBin - Local-only custom path to the codex binary; highest-priority runtime override for local Rust builds
  • baseUrl - Local-only OpenAI-compatible Responses API base URL passed to the launched app-server
  • apiKey - API key used for account/login/start
  • cwd - Local-only working directory for the app-server process
  • env - Local-only extra environment variables for the app-server process
• approval - Typed ApprovalHooks or the low-level legacy ApprovalHandler

Methods

• threadStart(params) - Create a new thread
  • Main place to set thread/session defaults such as model, sandbox, and approvalPolicy
• threadResume(threadId, params) - Resume an existing thread
• threadFork(threadId, params) - Fork an existing thread
• threadList(params) - List threads
• models(includeHidden?) - List visible models
• fsRemove({ path, recursive, force }) - Remove a file or directory tree through fs/remove
• projectDelete({ dirPath }) - Remove a project directory through fs/remove
• getClient() - Get underlying JSON-RPC client
• close() - Close connection to app-server

projectDelete uses fsRemove({ path: dirPath, recursive: true, force: true }). The app-server protocol does not provide a project/delete RPC; Gateway project record deletion remains the responsibility of the application layer.

Thread

Represents a conversation session.

Methods

• submit(input) - Submit a user message
• turn(input, options) - Start a turn and get a TurnHandle
• run(input, options) - Run a turn to completion
• read(includeTurns?) - Refresh thread metadata
• listTurns(params?) - Experimental historical turn pagination via thread/turns/list; intended for persisted history loading, not live runtime projection
• setName(name) - Set thread name
• archive() / unarchive() - Archive lifecycle
• compact() - Start thread compaction
• onEvent(handler) - Subscribe to events
• offEvent(handler) - Unsubscribe from events

Samples

The package now includes a small set of validation-oriented samples under samples:

• samples/basic_client.ts - low-level JsonRpcClient handshake and raw thread/start validation
• samples/basic_thread.ts - dev-heavy validation for initialize, threadStart(), turn() streaming, and aggregated run output
• samples/approval_handler.ts - validate typed approval hooks and command/file/user-input wiring

By default the samples look for the local debug Codex binary at ../../codex-rs/target/debug/codex. You can override it with CODEX_EXECUTABLE=/absolute/path/to/codex.

Runtime resolution priority is config.codexBin -> CODEX_EXECUTABLE -> bundled runtime -> PATH codex.

pnpm sample:client
pnpm sample:thread
pnpm sample:approval

Examples

The package also includes Python-style examples under examples:

• examples/01_quickstart.ts
• examples/02_turn_run.ts
• examples/03_turn_stream_events.ts
• examples/04_models_and_metadata.ts
• examples/05_existing_thread.ts
• examples/06_thread_controls.ts
• examples/07_image_and_text.ts
• examples/08_local_image_and_text.ts
• examples/09_async_parity.ts
• examples/10_error_handling_and_retry.ts
• examples/11_cli_mini_app.ts
• examples/12_turn_params_kitchen_sink.ts
• examples/13_model_select_and_turn_params.ts
• examples/14_turn_controls.ts
• examples/15_cloud_initialize.ts
• examples/16_cloud_project_list.ts
• examples/17_cloud_turn_run.ts
• examples/18_cloud_turn_stream_events.ts

Run them with:

pnpm example:01
pnpm example:02
pnpm example:03
pnpm example:04
pnpm example:05
pnpm example:06
pnpm example:07
pnpm example:08
pnpm example:09
pnpm example:10
pnpm example:11
pnpm example:12
pnpm example:13
pnpm example:14
pnpm example:15
pnpm example:16
pnpm example:17
pnpm example:18

09_async_parity intentionally documents that the TypeScript SDK already uses the async-style public surface by default, so there is no separate AsyncCodex class.

Architecture

This SDK differs from the official @openai/codex-sdk in key ways:

| Feature | Official SDK | App-Server SDK | | ---------------- | -------------------- | ------------------- | | Mode | codex exec | codex app-server | | Communication | Unidirectional | Bidirectional | | Approval Support | ❌ Not supported | ✅ Full support | | User Input | ❌ Not supported | ✅ Supported | | Protocol | JSONL (stdin/stdout) | JSON-RPC 2.0 |

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm build:watch

# Run tests
pnpm test

# Lint
pnpm lint

# Format
pnpm format:fix

License

MIT