Incursa.OpenAI.Codex

Incursa.OpenAI.Codex is an async-only .NET client for the local Codex runtime. It launches the codex executable as a subprocess, so the machine running your app must already have Codex installed and authenticated.

Source documentation lives in docs/ and is mirrored into incursa-docs for publication. Edit the source repository docs only; do not edit the mirrored output.

The public package is young, but the code comes from day-to-day Incursa Codex automation work rather than a throwaway wrapper. Incursa has processed more than 10,000 Codex messages while hardening local subprocess orchestration, streamed events, typed results, and failure handling around this SDK family.

It provides:

• CodexClient for starting and managing Codex conversations
• CodexThread and CodexTurn for stateful and turn-level control
• typed inputs, events, results, options, and exceptions such as CodexClientOptions, CodexThreadOptions, CodexTurnOptions, CodexInputItem, CodexThreadEvent, CodexThreadItem, CodexRunResult, CodexThreadSnapshot, CodexAccountReadResult, CodexAccountRateLimitsResult, CodexRuntimeCapabilities, CodexRuntimeMetadata, and CodexException
• an optional DI companion package, Incursa.OpenAI.Codex.Extensions, for IServiceCollection registration

When To Use This SDK

Use this SDK when you want a C# wrapper around the local Codex CLI and its thread or turn APIs.

• Good fit: repo-aware automation, server-side orchestration, and workflows that delegate work to a local Codex install.
• Use the OpenAI SDK when you want direct API calls from .NET.
• Use ChatKit when you want a hosted chat UI surface.
• Use the Agents SDK when you want higher-level agent orchestration.
• CodexClientOptions.ApiKey and CodexClientOptions.BaseUrl are forwarded to the Codex subprocess; they do not remove the local Codex installation requirement.
• If you want a no-throw preflight for the local executable, call await client.IsCodexAvailableAsync() before InitializeAsync() or any turn operation.

Start Here

The smallest useful call is a thread plus a single prompt:

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);

That example assumes the Codex runtime is installed locally and can authenticate through the environment or CodexClientOptions forwarded to the subprocess. CodexRunResult.FinalResponse can be null when a turn completes with commentary only and never emits a final-answer or phase-less assistant message.

If you need DI, install Incursa.OpenAI.Codex.Extensions and register CodexClient with AddCodex(...).

Validation

Use these commands from the repository root:

dotnet restore Incursa.OpenAI.Codex.slnx
dotnet build Incursa.OpenAI.Codex.slnx -c Release --no-restore
dotnet test Incursa.OpenAI.Codex.slnx -c Release --no-build -v minimal
dotnet pack src/Incursa.OpenAI.Codex/Incursa.OpenAI.Codex.csproj -c Release --no-build --output artifacts/packages /p:ContinuousIntegrationBuild=true
dotnet pack src/Incursa.OpenAI.Codex.Extensions/Incursa.OpenAI.Codex.Extensions.csproj -c Release --no-build --output artifacts/packages /p:ContinuousIntegrationBuild=true
git diff --check

See docs/maintainer-readiness.md for the focused test matrix, live-test opt-in commands, and release-floor details.

Which Backend Should I Use?

The CodexClientOptions type controls the runtime backend through its BackendSelection property.

Backend	Use it when	Good for	Not available
AppServer	you need the richer conversation surface	thread lifecycle, thread goals, model listing, account login/read/logout, account rate-limit reads, thread read/resume/fork/archive/unarchive, turn steering, turn interruption	N/A
Exec	you only need the CLI-backed run/stream path	quick one-shot prompts and streaming responses	thread lifecycle management, thread goals, model listing, account login/read/logout, account rate-limit reads, turn steering, turn interruption

The package currently defaults to AppServer.

At the transport level:

• AppServer maps to codex app-server --listen stdio://
• Exec maps to codex exec --experimental-json

What Is In The SDK?

The main public surfaces are:

• CodexClient: root entry point, async-only, IAsyncDisposable, ObserveEventsAsync() for the client-wide raw runtime event stream, account login/read/logout methods, GetAccountRateLimitsAsync() for app-server rate-limit windows, and IsCodexAvailableAsync() for an executable preflight
• CodexThread: stateful conversation handle with RunAsync, RunStreamedAsync, StartTurnAsync, ReadAsync, SetNameAsync, CompactAsync, GetGoalAsync, SetGoalAsync, SetGoalStatusAsync, and ClearGoalAsync
• CodexTurn: single-turn handle with StreamAsync, StreamNormalizedAsync, ObserveEventsAsync, ObserveNormalizedEventsAsync, RunAsync, RunToResultAsync, SteerAsync, and InterruptAsync
• CodexClientOptions, CodexThreadOptions, CodexTurnOptions: runtime, thread, and turn configuration
• CodexInputItem and derived types such as CodexTextInput, CodexImageInput, CodexLocalImageInput, CodexSkillInput, and CodexMentionInput
• CodexThreadEvent and CodexThreadItem hierarchies for raw streamed runtime data, including CodexTurnPlanUpdatedEvent for structured plan updates and CodexAccountRateLimitsUpdatedEvent when the app-server pushes a rate-limit update
• CodexTurnEvent, CodexTurnResult, and CodexTurnTerminalState for normalized turn output, final-response capture, terminal-event detection, and stream-ended-without-terminal diagnostics
• CodexRunResult, CodexThreadGoal, CodexThreadSnapshot, CodexAccountReadResult, CodexAccountRateLimitsResult, CodexRuntimeCapabilities, CodexRuntimeMetadata, and CodexException types for result handling and diagnostics. CodexRunResult.FinalResponse stays nullable for commentary-only turns.

For UI and delivery clients, use CodexClient.ObserveEventsAsync() as the exhaustive raw event channel across the client, and use CodexTurn.ObserveEventsAsync() or CodexTurn.ObserveNormalizedEventsAsync() when a caller needs replayed turn-scoped fan-out. Consumers that want Rx-style operators can layer System.Reactive over these IObservable<T> surfaces without the core package taking a dependency on it. Prefer CodexTurn.StreamNormalizedAsync() or CodexTurn.RunToResultAsync() when you need reliable turn closeout. CodexTurnResult.TerminalEventSeen distinguishes a real Codex terminal event from a stream that ended without turn.completed or turn.failed, and FinalResponseSource records whether the final answer came from the terminal event, a completed item, or accumulated assistant deltas.

Set CodexThreadOptions.ServiceTier or CodexTurnOptions.ServiceTier to CodexServiceTier.Fast to request upstream Fast mode. The SDK sends the current Codex request value, priority, while preserving the public Fast enum name.

Samples

The runnable sample in samples/Incursa.OpenAI.Codex.Sample demonstrates:

• quickstart
• streaming
• structured-output
• image-input
• error-handling
• turn-controls

See samples/Incursa.OpenAI.Codex.Sample/README.md for the sample overview and docs/sample-modes.md for the mode-by-mode commands.

Release And Versioning

• Package versioning and shared NuGet metadata live in Directory.Build.props.
• Release cuts are driven by scripts/release.ps1.
• Public API compatibility is tracked through PublicAPI.Shipped.txt and PublicAPI.Unshipped.txt in each package project.
• See docs/maintainer-readiness.md for the release and pack flow.

Deeper Docs

• docs/usage-guide.md
• docs/sample-modes.md
• samples/Incursa.OpenAI.Codex.Sample/README.md
• src/Incursa.OpenAI.Codex/README.md
• src/Incursa.OpenAI.Codex.Extensions/README.md
• docs/maintainer-readiness.md
• tests/Incursa.OpenAI.Codex.Tests/README.md
• fuzz/README.md
• benchmarks/README.md
• quality/testing-intent.yaml

Contributing And Security

• Read CONTRIBUTING.md before opening a pull request.
• Contributions are accepted under CONTRIBUTOR-AGREEMENT.md.
• Follow CODE_OF_CONDUCT.md in project spaces.
• Report vulnerabilities through SECURITY.md, not public issues.
• Do not commit secrets, local auth state, private transcripts, or repository paths from private worktrees.

Documentation Ownership

• docs/ is the source-authored documentation tree for this repository.
• Mirrored content in incursa-docs is generated from the source tree and should not be edited directly.
• Package-level consumer notes live under src/<PackageName>/ and are part of the source documentation set.

Known Gaps

• Live behavior depends on the installed codex executable, local Codex authentication, and upstream runtime behavior.
• Exec intentionally lacks app-server-only lifecycle and control capabilities.
• Upstream Python and TypeScript Codex SDK parity must be refreshed when upstream behavior changes.
• The repo still has maintenance items called out in docs/maintainer-readiness.md.

License

This repository is licensed under Apache 2.0. See LICENSE.