zeekay
eb49cac620
457 sites carried an upstream prefix into every surface a user reaches — shell exports, docs, CI, the SDK. CODEX_ is not our name and it was never going to stop arriving on its own: it is what upstream writes, and every sync brings more. Two namespaces, because they answer different questions. DEV_* the app's own configuration — DEV_HOME, DEV_PROFILE, the rest HANZO_API_KEY a credential for the Hanzo stack, which is not app config CODEX_API_KEY held the literal string "CODEX_API_KEY", so the rename moves the value and not just the constant. It becomes HANZO_API_KEY, which is what create_hanzo_provider already reads through HANZO_MACHINE_ENV_KEYS — one name for one credential instead of two spellings of it. vendor/ is untouched, which is the point of vendor/: upstream code keeps upstream names, and the boundary is a path rather than a habit.
2.0 KiB
Codex SDK
Embed the Codex agent in your workflows and apps.
The TypeScript SDK wraps the codex CLI from @openai/codex. It spawns the CLI and exchanges JSONL events over stdin/stdout.
Installation
npm install @openai/codex-sdk
Requires Node.js 18+.
Quickstart
import { Codex } from "@openai/codex-sdk";
const codex = new Codex();
const thread = codex.startThread();
const turn = await thread.run("Diagnose the test failure and propose a fix");
console.log(turn.finalResponse);
console.log(turn.items);
Call run() repeatedly on the same Thread instance to continue that conversation.
const nextTurn = await thread.run("Implement the fix");
Streaming responses
run() buffers events until the turn finishes. To react to intermediate progress—tool calls, streaming responses, and file diffs—use runStreamed() instead, which returns an async generator of structured events.
const { events } = await thread.runStreamed("Diagnose the test failure and propose a fix");
for await (const event of events) {
switch (event.type) {
case "item.completed":
console.log("item", event.item);
break;
case "turn.completed":
console.log("usage", event.usage);
break;
}
}
Resuming an existing thread
Threads are persisted in ~/.codex/sessions. If you lose the in-memory Thread object, reconstruct it with resumeThread() and keep going.
const savedThreadId = process.env.DEV_THREAD_ID!;
const thread = codex.resumeThread(savedThreadId);
await thread.run("Implement the fix");
Working directory controls
Codex runs in the current working directory by default. To avoid unrecoverable errors, Codex requires the working directory to be a Git repository. You can skip the Git repository check by passing the skipGitRepoCheck option when creating a thread.
const thread = codex.startThread({
workingDirectory: "/path/to/project",
skipGitRepoCheck: true,
});