Incursa.OpenAI.Codex 1.1.0

Incursa.OpenAI.Codex

Async-only Codex runtime for .NET. It wraps the local codex executable and starts it as a subprocess, so the machine running your app must already have Codex installed and authenticated. Any ApiKey or BaseUrl settings are forwarded to that subprocess; they do not replace the local Codex installation requirement.

This package is DI-agnostic and exposes the runtime API:

• CodexClient
• CodexThread
• CodexTurn
• typed options, event, item, result, and exception models such as CodexClientOptions, CodexThreadOptions, CodexTurnOptions, CodexInputItem, CodexThreadEvent, CodexThreadItem, CodexRunResult, CodexThreadSnapshot, CodexAccountRateLimitsResult, CodexRuntimeCapabilities, CodexRuntimeMetadata, and CodexException

When To Use This Package

Use this package when you want a .NET wrapper around the local Codex CLI for prompt/response flows, stateful threads, or turn-level control.

• Use the OpenAI SDK when you want direct API access from .NET.
• Use ChatKit when you want a hosted chat UI surface.
• Use the Agents SDK when you want higher-level agent orchestration.
• Use this package when you specifically want Codex-backed workflows driven from a local Codex install.
• If you want a no-throw preflight for the local executable, call await client.IsCodexAvailableAsync() before InitializeAsync() or any turn operation.

Hello World

The smallest useful call starts a thread, sends one prompt, and prints the final response:

using Incursa.OpenAI.Codex;

await using var client = new CodexClient();

CodexThread thread = await client.StartThreadAsync(new CodexThreadOptions
{
    SkipGitRepoCheck = true,
});

CodexRunResult result = await thread.RunAsync("Say hello from Codex in one sentence.");
Console.WriteLine(result.FinalResponse);

CodexRunResult.FinalResponse can be null when a turn completes with commentary only and never produces a final-answer or phase-less assistant message.

CodexClient is async-only. Dispose it with await using.

If you need DI registration, use Incursa.OpenAI.Codex.Extensions and call AddCodex(...).

Backend Modes

The API supports both backend modes:

• AppServer (codex app-server --listen stdio://) for the full JSON-RPC surface, thread lifecycle operations, model listing, account rate-limit reads, and turn steering or interruption
• Exec (codex exec --experimental-json) for the CLI-backed run and stream flow

Use AppServer when you need long-lived conversations, CodexThread management, or turn control. Use Exec when you only need prompt-in, response-out behavior.

Major API Surfaces

• CodexClient: the root entry point for runtime startup, thread management, model discovery, account rate-limit reads, and IsCodexAvailableAsync() for an executable preflight
• CodexThread: a stateful conversation handle with RunAsync, RunStreamedAsync, StartTurnAsync, ReadAsync, SetNameAsync, and CompactAsync
• CodexTurn: a single-turn handle with StreamAsync, RunAsync, SteerAsync, and InterruptAsync
• CodexClientOptions: backend selection, executable path override, API key, configuration, environment, and approval handler
• CodexThreadOptions and CodexTurnOptions: working directory, sandbox, approval, model, and output schema settings
• CodexInputItem and the typed input union for text, remote image, local image, skill, and mention inputs
• CodexThreadEvent, CodexThreadItem, CodexRunResult, CodexThreadSnapshot, CodexAccountRateLimitsResult, CodexAccountRateLimitsUpdatedEvent, CodexRuntimeCapabilities, CodexRuntimeMetadata, and CodexException for streamed data, results, and diagnostics. CodexRunResult.FinalResponse stays nullable for commentary-only turns.

Sample

The runnable sample under samples/Incursa.OpenAI.Codex.Sample shows quickstart, streaming, structured output, image input, error handling, and turn controls.

License

Apache 2.0. See the repository root LICENSE.