Zag 0.18.0

Zag C# Binding

C# binding for zag — a unified CLI for AI coding agents.

Prerequisites

• .NET 8.0+
• The zag CLI binary installed and on your PATH (or set via ZAG_BIN env var)

Installation

dotnet add package Zag

Quick start

using Zag;

var output = await new ZagBuilder()
    .Provider("claude")
    .Model("sonnet")
    .AutoApprove()
    .ExecAsync("write a hello world program");

Console.WriteLine(output.Result);

Streaming

using Zag;

await foreach (var evt in new ZagBuilder().Provider("claude").StreamAsync("analyze code"))
{
    Console.WriteLine($"{evt.Type}: {evt}");
}

Builder methods

Provider support for streaming / MCP flags

Four builder methods that toggle streaming I/O details and per-invocation MCP configuration are only honored by the Claude provider. Passing them to any other provider is a no-op.

.ExecStreaming() is Claude-only and always sets -i stream-json, -o stream-json, and --replay-user-messages. By default it emits one assistant_message event per complete assistant turn — you get one event when the model finishes speaking, not a stream of token chunks. Call .IncludePartialMessages(true) to receive token-level partial assistant_message chunks instead. The default stays false so existing callers that render whole-turn bubbles are not broken.

At the end of every agent turn the session emits a turn_complete event (C# type TurnCompleteEvent) carrying the provider's stop_reason (end_turn, tool_use, max_tokens, stop_sequence, or null), a zero-based monotonic turn_index, and the turn's usage. A per-turn result event fires immediately after. New code should key turn-boundary UI off turn_complete — it is the authoritative signal and carries richer metadata than result. result continues to fire per-turn for backward compatibility.

Terminal methods

Version checking

The SDK automatically checks the installed zag CLI version before running commands. If you use a builder method that requires a newer CLI version than what's installed, a clear error is raised:

Env() requires zag CLI >= 0.6.0, but the installed version is 0.5.0.
Please update the zag binary.

The version is detected once (by running zag --version) and cached for the lifetime of the process.

All other methods are available since the initial release (0.2.3).

Discovery

Static async methods for discovering available providers, models, and capabilities:

using Zag;

string[] providers = await ZagDiscover.ListProvidersAsync();
ProviderCapability cap = await ZagDiscover.GetCapabilityAsync("claude");
ProviderCapability[] all = await ZagDiscover.GetAllCapabilitiesAsync();
ResolvedModel resolved = await ZagDiscover.ResolveModelAsync("claude", "small");

How it works

The SDK spawns the zag CLI as a subprocess (zag exec -o json or -o stream-json) and parses the JSON/NDJSON output into typed models. Zero external dependencies — only the .NET standard library.

Testing

dotnet test

See also

• TypeScript SDK
• Python SDK
• Rust API (zag-agent)
• All bindings

License

MIT