codex-app-server-client

TypeScript client library for codex app-server.

The package exposes a single supported public entrypoint: the root package import codex-app-server-client. That root import provides a typed, layered client surface:

• transport/ for newline-delimited JSON over stdio
• rpc/ for request/response correlation and initialize-state enforcement
• protocol/ for curated generated protocol bindings
• client/ for ergonomic APIs like thread.start(), turn.run(), and approval handling

For the common local case, the package also exposes a zero-config createClient() factory that starts a local app-server, completes initialize -> initialized, and returns a ready-to-use client.

Subpath imports are intentionally not part of the public contract.

Documentation

• Published docs: brandonmjohnson.github.io/codex-client
• Guide: Guide
• API overview: API Surface
• Client reference: AppServerClient
• Changelog: CHANGELOG.md
• Release process: RELEASING.md

Status

The project is under active development. The stable stdio client surface is implemented and covered by unit and live integration tests.

The active roadmap lives in IMPLEMENTATION_PLAN.md.

Requirements

• Node.js 24+
• A local codex CLI when you want to run against a real app-server process

Install

The package is published on npm, is ESM-only, and exposes only the root package entrypoint. Consumers should use import / export syntax; CommonJS require() is intentionally unsupported.

For local development from this checkout:

npm ci

For consumption from another project:

npm install codex-app-server-client

Validation

npm run typecheck
npm run build
npm test
npm run docs:build

When you want to exercise the real app-server flow locally, run the live integration suite separately:

npm run test:integration