@peezy.tech/codex-flows

Workspace package for talking to codex app-server.

This package owns the low-level JSON-RPC client, transports, framework-agnostic flow helpers, and generated Codex app-server protocol types.

Exports

@peezy.tech/codex-flows
- CodexAppServerClient
- CodexStdioTransport
- CodexWebSocketTransport
- JSON-RPC helpers and types
@peezy.tech/codex-flows/browser
- browser-safe CodexAppServerClient
- CodexWebSocketTransport
- JSON-RPC helpers and types
@peezy.tech/codex-flows/flows
- CodexFlowClient
- createCodexFlowClient
- prompt/input normalization and optional turn completion waiting
@peezy.tech/codex-flows/auth
- CodexAuthClient
- createCodexAuthClient
- privacy-preserving Codex account login, status, and usage helpers
@peezy.tech/codex-flows/rpc
- JSON-RPC message types and parsing helpers
@peezy.tech/codex-flows/generated
- generated Codex app-server protocol types
@peezy.tech/codex-flows/generated/*
- generated per-type modules

Transports

CodexAppServerClient defaults to a stdio transport that starts codex app-server when no explicit transport is provided.

It can also connect to an existing WebSocket app-server when CODEX_WORKSPACE_APP_SERVER_WS_URL is set, or when webSocketTransportOptions.url is passed.

import { CodexAppServerClient } from "@peezy.tech/codex-flows";

const client = new CodexAppServerClient();
await client.connect();

const threads = await client.listThreads({});

client.close();

Browser entry:

import { CodexAppServerClient } from "@peezy.tech/codex-flows/browser";

const client = new CodexAppServerClient({
	webSocketTransportOptions: { url: "ws://127.0.0.1:3585" },
});
await client.connect();

Flow helpers:

import { createCodexFlowClient } from "@peezy.tech/codex-flows/flows";

const codex = createCodexFlowClient({
	appServerUrl: "ws://127.0.0.1:3585",
});

const result = await codex.startFlow({
	cwd: "/path/to/app",
	prompt: "Run the app-specific Codex workflow.",
	approvalPolicy: "never",
	sandbox: "danger-full-access",
	wait: false,
});

console.log(result.threadId, result.turnId);

Auth helpers:

import {
	CodexAppServerClient,
	createCodexAuthClient,
} from "@peezy.tech/codex-flows";

const client = new CodexAppServerClient();
await client.connect();

const auth = createCodexAuthClient(client);
const state = await auth.getState();

if (state.status !== "authenticated") {
	const login = await auth.startChatGptLogin();
	console.log(login.authUrl);
}

The high-level auth state intentionally omits email addresses and stable account identifiers. It exposes anonymous auth mode, plan, and usage data by default. Call the lower-level app-server client directly only when an application has an explicit reason to handle raw account details.

Scripts

bun run --filter @peezy.tech/codex-flows build
bun run --filter @peezy.tech/codex-flows check:types
bun run --filter @peezy.tech/codex-flows test
bun run --filter @peezy.tech/codex-flows pack:dry-run
bun run --filter @peezy.tech/codex-flows release:check

build emits ESM JavaScript, source maps, and declaration files into dist.

Install

After publishing, install the package from npm:

bun add @peezy.tech/codex-flows

or:

npm install @peezy.tech/codex-flows

Publishing

Run the release check before publishing:

bun run --filter @peezy.tech/codex-flows release:check

The release check runs package tests, type checking, a clean dist build, and npm pack --dry-run. Review the pack output before publishing so only dist, README.md, and package metadata are included.

For the first publish, use a human npm session or short-lived npm token from the public peezy-tech/codex-flows repo checkout. The peezy.tech npm organization/scope must exist first, and the publishing account or token must have write access to that scope:

cd packages/codex-client
npm publish --access public

After @peezy.tech/codex-flows exists on npm, configure trusted publishing for .github/workflows/publish-codex-flows.yml in the public peezy-tech/codex-flows repo. Future publishes should run through GitHub Actions without an npm token.

Notes

Generated protocol files live in src/app-server/generated. Keep handwritten client and transport code outside that generated tree.

4.3 KiB Raw Blame History