TypeScript SDK

Embed the Frontal coding agent in a Node.js application with a typed client.

Table of Contents

Start and continue a thread
Stream events
Resume a thread
Structured output and images
Configuration

The TypeScript SDK wraps the frontal CLI from @frontal/sdk. It starts the CLI and exchanges JSONL events over stdin/stdout. It requires Node.js 18+.

npm install @frontal/sdk

Start and continue a thread

import { Codex } from "@frontal/sdk";
 
const codex = new Codex();
const thread = codex.startThread({ workingDirectory: process.cwd() });
const turn = await thread.run("Review the authentication flow and list risks");
 
console.log(turn.finalResponse);
console.log(turn.items);

Stream events

run() buffers until the turn finishes. Use runStreamed() for progress, tool calls, file changes, and usage:

const { events } = await thread.runStreamed("Run the test suite and explain failures");
 
for await (const event of events) {
  if (event.type === "item.completed") console.log(event.item);
  if (event.type === "turn.completed") console.log(event.usage);
}

Resume a thread

Threads persist in ~/.frontal/sessions. Save the thread ID and resume it later:

const thread = codex.resumeThread(process.env.CODEX_THREAD_ID ?? "");
await thread.run("Continue where we left off");

Structured output and images

Pass a JSON Schema for machine-readable output:

const turn = await thread.run("Summarize repository status", {
  outputSchema: {
    type: "object",
    properties: {
      summary: { type: "string" },
      status: { type: "string", enum: ["ok", "action_required"] },
    },
    required: ["summary", "status"],
    additionalProperties: false,
  } as const,
});

Attach local images with structured input entries:

await thread.run([
  { type: "text", text: "Describe this screenshot" },
  { type: "local_image", path: "./ui.png" },
]);

Codex accepts env, config, and configOverrides. A thread can set workingDirectory and skipGitRepoCheck. The SDK inherits the Node.js process environment by default; supply env when the child process must receive a restricted environment. See the SDK README for the complete options and item types.

Updated Sep 17, 2026

Start and continue a thread

Stream events

Resume a thread

Structured output and images

Configuration