Codex App Client

TypeScript client for the Codex App Server stdio JSON-RPC protocol.

Protocol types are kept aligned with the official app-server docs and the installed Codex CLI schema generator:

codex app-server generate-ts --out ./schemas

Install

npm install @happycatlabs/codex-client
# or
bun add @happycatlabs/codex-client

Quick Start

import { CodexClient } from "@happycatlabs/codex-client";

const client = new CodexClient({
  model: "gpt-5.3-codex",
  cwd: "/path/to/your/repo",
  approvalPolicy: "never",
});

await client.connect();

const thread = await client.startThread({});

const result = await client.runTurn({
  threadId: thread.id,
  input: [{ type: "text", text: "List all TypeScript files in src/" }],
});

console.log(result.agentMessage);

await client.disconnect();

API Reference

Method	Description	Key Params	Return Type
connect()	Spawn the app-server and complete the initialize handshake	—	Promise<void>
disconnect()	Close the transport and kill the app-server process	—	Promise<void>
startThread(params)	Create a new thread	StartThreadParams	Promise<Thread>
resumeThread(threadId, params?)	Resume an existing thread	threadId: string, ResumeThreadParams?	Promise<Thread>
forkThread(threadId)	Fork a thread into a new copy	threadId: string	Promise<Thread>
readThread(threadId, includeTurns?)	Read thread metadata (optionally with turn history)	threadId: string, includeTurns?: boolean	Promise<Thread>
listThreads(params?)	List threads with optional cursor pagination	ListThreadsParams?	Promise<ThreadListResult>
listThreadTurns(params)	Page through stored turn history with optional item detail view	ThreadTurnsListParams	Promise<ThreadTurnsListResult>
listThreadTurnItems(params)	Reserved API for paging items within one stored turn	ThreadTurnsItemsListParams	Promise<ThreadTurnsItemsListResult>
archiveThread(threadId)	Archive a thread	threadId: string	Promise<void>
compactThread(threadId)	Compact a thread's history	threadId: string	Promise<void>
startTurn(params)	Start a turn and return immediately (non-blocking)	StartTurnParams	Promise<Turn>
runTurn(params)	Start a turn and wait for full completion, collecting all items	StartTurnParams	Promise<CompletedTurn>
steerTurn(params)	Steer an in-progress turn with new input	SteerTurnParams	Promise<string> (turnId)
interruptTurn(threadId, turnId)	Interrupt an in-progress turn	threadId: string, turnId: string	Promise<void>
startReview(params)	Start a code review turn	StartReviewParams	Promise<ReviewResult>
runReview(params)	Start a review and wait for completion	StartReviewParams	Promise<CompletedReview>
listModels(params?)	List available models	ListModelsParams?	Promise<ModelListResult>
execCommand(params)	Execute a sandboxed shell command (no thread)	ExecCommandParams	Promise<ExecCommandResult>

Recent Codex app-server fields are exposed on the matching params/types: approvalsReviewer, sessionStartSource, threadSource, array-valued listThreads.cwd, listThreads.useStateDbOnly, and model serviceTiers.

Events

Event	Payload	Description
turn:started	Turn	A new turn began
turn:started:notification	TurnStartedNotification	A new turn began, including thread context
turn:completed	Turn	A turn finished (check turn.status)
turn:completed:notification	TurnCompletedNotification	A turn finished, including thread context
item:started	ThreadItem	An item (message, command, file change, etc.) began
item:started:notification	ItemNotification	An item began, including thread and turn context
item:completed	ThreadItem	An item finished
item:completed:notification	ItemNotification	An item finished, including thread and turn context
rawResponseItem:completed	ResponseItem	A raw Responses API item finished
rawResponseItem:completed:notification	RawResponseItemCompletedNotification	A raw Responses API item finished with thread context
item:agentMessage:delta	{ itemId: string; delta: string }	Streaming text chunk from the agent
item:agentMessage:delta:notification	AgentMessageDeltaNotification	Streaming text chunk with thread and turn context
item:commandExecution:outputDelta	{ itemId: string; delta: string }	Streaming output from a command
item:commandExecution:outputDelta:notification	CommandOutputDeltaNotification	Streaming command output with thread and turn context
item:mcpToolCall:progress	{ itemId: string; message: string }	Streaming progress from an MCP tool call
item:mcpToolCall:progress:notification	McpToolCallProgressNotification	Streaming MCP progress with thread and turn context
turn:diff:updated	{ threadId: string; turnId: string; diff: string }	Cumulative diff for the current turn
turn:diff:updated:notification	DiffUpdatedNotification	Cumulative diff notification
turn:plan:updated	{ threadId?: string; turnId: string; plan: PlanEntry[] }	Agent plan updated
turn:plan:updated:notification	PlanUpdatedNotification	Agent plan update notification
turn:plan:delta	PlanDeltaNotification	Streaming plan text delta
turn:plan:delta:notification	PlanDeltaNotification	Streaming plan text delta notification
thread:started	Thread	A new thread was created
thread:status:changed	ThreadStatusChangedNotification	Loaded thread runtime status changed
error	Error	Transport-level error (process crash, socket close, etc.)

CodexClientOptions

Field	Type	Default	Description
clientName	string	"openclaw"	Identifies this client in the initialize handshake
clientVersion	string	"0.1.0"	Client version sent during initialize
model	string	"gpt-5.3-codex"	Default model for threads and turns
cwd	string	process.cwd()	Working directory for the spawned app-server
approvalPolicy	"never" | "unlessTrusted" | "always"	"never"	When to ask for approval before running commands
sandbox	string	"workspace-write"	Sandbox policy name
experimentalApi	boolean	true	Enable experimental protocol features
codexPath	string	"codex"	Path to the codex binary

runTurn() vs startTurn()

Use runTurn() when you want fire-and-forget behavior: send input, wait for the agent to finish, get back the full result including all items, the final agent message, and the cumulative diff. This covers the vast majority of use cases.

const { agentMessage, items, diff } = await client.runTurn({
  threadId: thread.id,
  input: [{ type: "text", text: "Refactor this function" }],
});

Use startTurn() when you need to react to streaming events while the turn is in progress — for example, to pipe item:agentMessage:delta events to a UI in real time, or to conditionally steer/interrupt the turn based on what the agent is doing.

client.on("item:agentMessage:delta", ({ text }) => process.stdout.write(text));
client.on("item:commandExecution:outputDelta", ({ output }) => process.stdout.write(output));

const turn = await client.startTurn({
  threadId: thread.id,
  input: [{ type: "text", text: "Run the tests" }],
});

// turn is in progress — listen to events, steer or interrupt if needed
// Wait manually:
await new Promise<void>((resolve) => {
  client.once("turn:completed", (t) => {
    if (t.id === turn.id) resolve();
  });
});

Large Thread History

thread/turns/list supports itemsView: "notLoaded" | "summary" | "full" on Codex 0.130.0+. Omit it only when you intentionally want the app-server default. Use "summary" for large-thread history UIs that need compact display items before selectively hydrating heavier detail.

thread/turns/items/list is exposed as listThreadTurnItems() for protocol completeness, but Codex 0.130.0 currently returns an unsupported-method JSON-RPC error for it.

Testing

bun test

Unit tests mock the transport layer. Integration tests (in src/__tests__/integration.test.ts) require a real codex binary and are automatically skipped when it is not available.