How to run a Codex task with the TypeScript SDK

Embedding Codex in a server-side tool lets a build script, dashboard, or internal workflow start a coding task without opening the interactive CLI. The TypeScript Codex SDK wraps the local Codex runtime, creates a thread, sends a prompt, and returns the final assistant response to the calling Node.js process.

The SDK runs from the working directory passed to startThread(), so repository context, AGENTS.md, execution permissions, and login state still matter. A read-only thread can inspect the project's files without changing them, which suits a task that retrieves the package name.

You need Node.js 18 or later, npm, and a Git project containing a package.json with a nonempty name field. The runtime user needs a working Codex model configuration and any authentication that provider requires. Project content can reach the configured model provider, so the selected project must be one you are allowed to share with it.

1. Select the project whose package name you want to retrieve.

   $ cd ~/projects/example-app

   The current directory becomes the thread's working directory. example-app represents your own Git project.
   Related: How to fix the Codex trusted-directory error
   Related: How to set the working directory for Codex

2. Install the official SDK dependency in the project.

   $ npm install @openai/codex-sdk

   This updates package.json and package-lock.json. The SDK is a server-side library, not a browser bundle.

3. Create run-codex-task.mjs in the project root using your text editor.

   run-codex-task.mjs

   import { Codex } from "@openai/codex-sdk";
    
   const codex = new Codex();

   new Codex() creates the client using the bundled runtime. The .mjs extension lets Node.js run the module directly without a TypeScript compiler.

4. Append the thread definition after the client initialization in run-codex-task.mjs.

   const thread = codex.startThread({
     workingDirectory: process.cwd(),
     sandboxMode: "read-only",
     approvalPolicy: "never",
   });

   The thread uses the selected project root and read-only permissions. The approval policy makes an unattended task fail rather than wait for permission to perform a blocked action.

5. Append the package-reading task and response output at the end of run-codex-task.mjs.

   const turn = await thread.run(
     "Use a shell command to read package.json in the working directory. " +
     "Reply with only its name string, without formatting or extra lines. " +
     "Do not edit any files."
   );
    
   console.log(turn.finalResponse);

   The prompt supplies the task rather than the answer. thread.run() waits for the turn to finish, and finalResponse contains its final assistant text.

6. Save run-codex-task.mjs in your text editor.
7. Run the SDK task from the project root.

   $ node run-codex-task.mjs
   catalog-service

   The printed value should match the name field in your project's package.json; it will differ for another package. A blank response, a different name, or a runtime error does not confirm that the task completed. Any required authentication must be available to the runtime before the task can complete.
   Related: How to check Codex login status
   Related: How to log in to Codex CLI with an API key