JKToolKit.CodexSDK

A strongly-typed .NET SDK for the Codex CLI — launch it as a subprocess, stream events, and build integrations with a clean async API.

Three Integration Modes

Mode	Best for	Docs
codex exec	Stream JSONL session events from normal Codex runs	Exec docs
codex app-server	Deep, event-driven integrations, including remote stdio and WebSocket attach	App Server docs
codex mcp-server	Using Codex as an MCP tool provider	MCP Server docs

Install

dotnet add package JKToolKit.CodexSDK

Prerequisites: .NET 10+ and Codex CLI on your PATH.

SDK package versions follow the Codex CLI release, starting at 0.160.0. Additional SDK releases for the same CLI increment the patch (0.160.1, 0.160.2, etc.). See package versioning.

Quickstart

using JKToolKit.CodexSDK;
using JKToolKit.CodexSDK.Models;

await using var sdk = CodexSdk.Create();

// --- Exec mode: stream session events ---
await using var session = await sdk.Exec.StartSessionAsync(
    new CodexSessionOptions("<workdir>", "Write a hello world program")
    {
        Model = CodexModel.Gpt53Codex
    });

await foreach (var evt in session.GetEventsAsync())
{
    Console.WriteLine(evt);
}

// --- App Server: threads + turns + streaming deltas ---
await using var app = await sdk.AppServer.StartAsync();

// --- MCP Server: tool discovery + invocation ---
await using var mcp = await sdk.McpServer.StartAsync();

Documentation

Full docs, examples, and API reference live in docs/:

• Exec mode — sessions, streaming events, structured outputs, code reviews
• App Server — threads, turns, approvals, DI, resiliency
• MCP Server — tool discovery, sessions, follow-ups
• Semantic Kernel package
• Microsoft Agent Framework package

Demo

dotnet run --project src/JKToolKit.CodexSDK.Demo -- "Your prompt here"

See more demo commands in the full docs.

License & Contributing

Contributions welcome — open issues or pull requests for bugs, features, or docs.

High-level thread API

await using var sdk = await CodexSdk.StartAsync();
var thread = await sdk.Threads.StartAsync(new() { Cwd = repo });
var result = await thread.RunAsync("Fix the failing tests");
Console.WriteLine(result.FinalResponse);

Collected results, streaming subscriptions, trust-labelled external messages, optional pinned runtimes, preflight, middleware, and OpenTelemetry instrumentation are described in the high-level SDK guide.