Building with the Codex SDK

Your team wants an internal dashboard where product managers can click “Fix this bug” on a Jira ticket and have Codex automatically analyze the issue, propose a fix, and open a PR. Or maybe you need a nightly cron job that reviews all open PRs and posts summaries. The Codex CLI handles one-off tasks; the SDK lets you build Codex into your own applications.

What You’ll Walk Away With

• A working TypeScript integration that starts Codex threads, sends prompts, and processes results
• Patterns for multi-turn conversations, session resumption, and error handling
• Architecture guidance for building internal tools, dashboards, and automated pipelines with the SDK
• Security best practices for API key management in server-side applications

Getting Started

The SDK requires Node.js 18+ and runs server-side only.

npm install @openai/codex-sdk

Basic Usage

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const turn = await thread.run(
  "Analyze the test failures in the CI logs and propose fixes"
);

console.log(turn.finalResponse);

The run() method sends a prompt to Codex, waits for the agent to complete its work (including file reads, edits, and command execution), and resolves to a turn object. The agent’s final text is on turn.finalResponse; the full list of actions it took is on turn.items, and streaming runs expose token counts on turn.usage.

Multi-Turn Conversations

Call run() again on the same thread to continue the conversation:

// First turn: analyze
const analysis = await thread.run(
  "Review the authentication module for security issues"
);

// Second turn: fix what was found
const fixes = await thread.run(
  "Implement the fixes you identified. Run the test suite after each change."
);

Resuming Past Threads

If you need to continue a previous session (e.g., a two-stage pipeline), provide the thread ID:

const threadId = "01912345-abcd-7890-ef01-234567890abc";
const thread = codex.resumeThread(threadId);
const result = await thread.run("Pick up where you left off and finish the migration");

Prompt: Build a bug-fix pipeline with the SDK

import { Codex } from "@openai/codex-sdk";

async function fixBug(issueDescription: string, repo: string) {
  const codex = new Codex();
  const thread = codex.startThread();

  // Step 1: Diagnose
  const diagnosis = await thread.run(
    `Given this bug report, identify the root cause in the codebase:\n\n${issueDescription}`
  );

  // Step 2: Fix
  const fix = await thread.run(
    "Implement the minimal fix. Run tests to verify. Do not refactor unrelated code."
  );

  // Step 3: Validate
  const validation = await thread.run(
    "Run the full test suite and lint checks. Report the results."
  );

  return {
    diagnosis: diagnosis.finalResponse,
    fix: fix.finalResponse,
    validation: validation.finalResponse,
  };
}

Architecture Patterns

Internal Dashboard

Build a web API that exposes Codex operations to internal tools:

// POST /api/codex/task
app.post("/api/codex/task", async (req, res) => {
  const { prompt, projectPath } = req.body;

  const codex = new Codex();
  const thread = codex.startThread();

  try {
    const turn = await thread.run(prompt);
    res.json({
      result: turn.finalResponse,
      status: "completed"
    });
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    res.status(500).json({ error: message });
  }
});

Scheduled Pipeline

Combine the SDK with a job scheduler for recurring tasks:

import { CronJob } from "cron";

const nightlyReview = new CronJob("0 2 * * *", async () => {
  const codex = new Codex();
  const thread = codex.startThread();

  const turn = await thread.run(
    "Review all PRs opened in the last 24 hours. " +
    "For each PR, summarize the changes and flag any security concerns. " +
    "Output a JSON array with pr_number, summary, and risk_level fields."
  );

  await postToSlack("#engineering", turn.finalResponse);
});

nightlyReview.start();

SDK vs codex exec vs Cloud Tasks

Feature	SDK	codex exec	Cloud Tasks
Programmatic control	Full	CLI flags + stdin/stdout	Web UI + integrations
Multi-turn conversations	Native	Resume with --last	Follow-up in thread
Environment	Your server	Your machine / CI runner	OpenAI’s containers
Best for	Custom apps, dashboards	CI/CD scripts, one-off automation	Delegated work, mobile triage

When This Breaks

• Authentication errors: The SDK uses the same credentials as the CLI. Ensure CODEX_API_KEY is set or run codex login on the machine running the SDK.
• Thread timeouts: Long-running tasks may hit API timeouts. Break complex work into smaller run() calls rather than one massive prompt.
• Rate limits: The SDK is subject to the same rate limits as your plan. Monitor usage with /status in the CLI or the usage dashboard.
• Stale thread state: If you resume a thread from days ago, the codebase may have changed. Include context about recent changes in your follow-up prompt.

What’s Next

• Non-Interactive Mode — For simpler scripting needs, codex exec may be sufficient
• GitHub Action — Pre-built CI/CD integration without writing SDK code
• Cost Management — SDK usage counts against your plan limits