Universal.Anthropic.ClaudeAgentSdk 2.0.3

Universal.Anthropic.ClaudeAgentSdk

⚠️ Unofficial. This is an independent, third-party wrapper — not published, maintained, endorsed, or supported by Anthropic.

• "Claude", "Claude Code", and "Anthropic" are trademarks of Anthropic PBC, referenced here only to describe compatibility.
• Provided as-is, with no warranty. Parts of the underlying CLI wire protocol aren't officially documented and may change without notice; review the source and test against your own use case before relying on this in production.
• You need your own Anthropic API key or Claude subscription — this package doesn't provide access, credentials, or billing of any kind.

Universal.Anthropic.ClaudeAgentSdk is a C# library for running the Claude Code CLI as a subprocess and consuming its stream-json output, in the same spirit as Anthropic's official TypeScript/Python Claude Agent SDKs.

It does not bundle the claude executable inside the NuGet package, but it can find one for you in three ways:

• ClaudeCodeExecutableSource.SystemPath (default) — resolves claude/claude.exe from PATH. Install it separately with npm install -g @anthropic-ai/claude-code or a platform installer.
• ClaudeCodeExecutableSource.Download — downloads the official native binary for your OS/architecture directly from downloads.claude.ai (the same source the official install scripts use), verifies its SHA-256 checksum against the published release manifest, and caches it under your local application data folder. No Node.js, npm, or shell installer required — this works the same way on Windows, macOS, and Linux.
• ClaudeCodeExecutableSource.SystemPathThenDownload — tries PATH first (so a machine that already has Claude Code installed keeps using that installation), and only downloads a cached copy if nothing is found. This is resolved lazily on each query, not at startup, so it always reflects whatever's on PATH at execution time.
• ClaudeCodeQuery.Options.Executable.ClaudeCodePath — set this to use a claude binary you already have (e.g. one your application bundles itself). It always wins over Source when set.

Executable is its own ClaudeCodeExecutableOptions type (ClaudeCodePath, Source, DownloadVersion, DownloadCacheDirectory) rather than living directly on ClaudeCodeQuery.Options, because ClaudeCodeDownloader only ever needs those four settings — not the rest of ClaudeCodeQuery.Options (Model, SystemPrompt, AllowedTools, etc.), which are query-only concerns. Call ClaudeCodeDownloader directly with just a ClaudeCodeExecutableOptions if you want to manage the binary independently of running any query.

Updating a downloaded binary

Once ClaudeCodeDownloader has cached a binary for a platform, EnsureDownloadedAsync (and therefore ExecutableSource.Download/SystemPathThenDownload) never checks the network again on its own, even with DownloadVersion left at the default "latest" — it just keeps using what's cached. Call these explicitly on whatever schedule suits your application:

// Check without downloading anything.
var check = await ClaudeCodeDownloader.CheckForUpdateAsync(options.Executable);
if (check.IsUpdateAvailable)
{
    Console.WriteLine($"{check.InstalledVersion ?? "(none)"} -> {check.LatestVersion} available");
}

// Fetch and cache whatever's currently latest, regardless of what's cached.
string updatedPath = await ClaudeCodeDownloader.UpdateAsync(options.Executable);

Old cached versions aren't deleted automatically; prune ClaudeCodeExecutableOptions.DownloadCacheDirectory yourself if that matters for your deployment.

Using a Claude Pro/Max/Team subscription instead of API billing

This SDK never touches authentication itself — it just spawns claude, which reads whatever credentials it's already configured with:

• If claude has already been logged into interactively on the machine (claude → browser login), the subprocess reuses that cached credential (OS keychain on macOS, ~/.claude/.credentials.json on Linux, %USERPROFILE%\.claude\.credentials.json on Windows) automatically. Nothing to configure.
• For headless machines (CI, servers, containers), run claude setup-token once to mint a one-year OAuth token tied to the Pro/Max/Team/Enterprise subscription, then pass it through:

  options.EnvironmentVariables = new Dictionary<string, string> { ["CLAUDE_CODE_OAUTH_TOKEN"] = "..." };
  

  This bills against the subscription's quota rather than pay-per-token API usage.

Two gotchas: CLAUDE_CODE_OAUTH_TOKEN is ignored when ClaudeCodeQuery.Options.Bare is true; and if ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN is also present in the subprocess's inherited environment, it takes precedence over both the OAuth token and any interactive subscription login, so a stray API key env var will silently switch you to pay-per-token billing.

Logging in from code, including across devices

For a machine with no browser of its own (a remote box, a container), ClaudeCodeQuery.AuthenticateAsync drives the same OAuth login the CLI's own claude/claude setup-token commands use, but over the control channel instead of an interactive TUI:

var query = await ClaudeCodeClient.StartAsync(options);
OAuthAuthenticationUrls urls = await query.AuthenticateAsync();

// urls.AutomaticUrl only completes if opened on this same machine (localhost redirect).
// urls.ManualUrl works from literally any device/browser -- open it anywhere, log in,
// and its success page displays a code instead of redirecting.
Console.WriteLine($"Open this URL on any device to log in: {urls.ManualUrl}");

string pastedCode = Console.ReadLine(); // paste the "authorizationCode#state" shown on that page
AccountInfo account = await query.SubmitOAuthCallbackAsync(pastedCode);

If a browser is available on the same machine instead, open urls.AutomaticUrl there and call WaitForOAuthCompletionAsync() instead of SubmitOAuthCallbackAsync — it blocks until the CLI's own localhost redirect listener resolves the flow, with no code to paste. Either way, once the flow completes the same session picks up the new credentials immediately; no respawn needed. Both completion calls are genuine network round trips (token exchange), so pass a generous timeout rather than the default.

Usage

var options = new ClaudeCodeQuery.Options
{
    WorkingDirectory = @"C:\my\project",
    AllowedTools = new[] { "Read", "Grep" },
};

// `await using` is required: a plain `await foreach` alone does not stop the subprocess when the loop
// ends -- this class supports resuming the same conversation with further turns after a bare `await foreach`
// completes, so only an explicit Dispose/CloseAsync (not "the loop finished") means "I'm done with this query."
var query = ClaudeCodeClient.Query("What does this repo do?", options);
await using (query)
{
    await foreach (var message in query)
    {
        switch (message)
        {
            case AssistantMessage assistant:
                Console.WriteLine(assistant.Message.Content);
                break;
            case ResultMessage result:
                Console.WriteLine($"Cost: ${result.TotalCostUsd}");
                break;
        }
    }
}