ClaudeAgentSDK.NET 0.1.0

ClaudeAgentSDK.NET

A C# SDK for programmatic access to Claude Code CLI with hooks, streaming, and configuration management. This is the .NET implementation of the official Claude Agent SDK.

Status

Version 0.1.0 - Core implementation complete with 361 tests passing.

Features

• Simple API - One-shot queries with Claude.QueryAsync() and Claude.AskAsync()
• Advanced API - Multi-turn conversations with ClaudeClient
• Hook System - Intercept tool executions (PreToolUse, PostToolUse, etc.)
• Configuration Management - Manage .claude/ settings, agents, commands
• MCP Integration - Configure and manage MCP servers
• Cross-Platform - Windows, Linux, macOS support
• PowerShell Module - Full PowerShell cmdlet support (PSClaudeAgentSDK)

Installation

# NuGet (when published)
dotnet add package ClaudeAgentSDK.NET

# PowerShell Gallery (when published)
Install-Module PSClaudeAgentSDK

Quick Start

C# - Simple Query

using ClaudeAgentSDK.NET;

// One-liner for simple questions
var answer = await Claude.AskAsync("What is 2+2?");
Console.WriteLine(answer);

// Streaming messages
await foreach (var message in Claude.QueryAsync("Explain recursion"))
{
    if (message is AssistantMessage am)
        Console.WriteLine(am.GetText());
}

C# - With Options

var options = new ClaudeOptions
{
    Model = "claude-sonnet-4-20250514",
    MaxTurns = 5,
    AllowedTools = new[] { "Read", "Write", "Bash" },
    SystemPrompt = "You are a helpful assistant."
};

await foreach (var message in Claude.QueryAsync("Help me debug this code", options))
{
    // Process messages
}

C# - Stateful Client

await using var client = new ClaudeClient(options);
await client.ConnectAsync();

// Multi-turn conversation
await foreach (var msg in client.QueryAsync("Remember the number 42"))
    ProcessMessage(msg);

await foreach (var msg in client.QueryAsync("What number did I mention?"))
    ProcessMessage(msg);

// Interrupt if needed
await client.InterruptAsync();

C# - With Hooks

var options = new ClaudeOptions
{
    Hooks = new Dictionary<string, List<HookMatcher>>
    {
        ["PreToolUse"] = new List<HookMatcher>
        {
            new HookMatcher
            {
                Matcher = new ToolMatcher { ToolName = "Bash" },
                Hooks = new List<HookCallback>
                {
                    new HookCallback
                    {
                        Type = "callback",
                        Callback = async (context, ct) =>
                        {
                            // Block dangerous commands
                            if (context.ToolInput?.Contains("rm -rf") == true)
                                return new HookResult { Decision = HookDecision.Block };
                            return new HookResult { Decision = HookDecision.Allow };
                        }
                    }
                }
            }
        }
    }
};

PowerShell

# Import the module
Import-Module PSClaudeAgentSDK

# Simple query
Invoke-Claude -Prompt "What is 2+2?" -AsText

# With options
$options = New-ClaudeOptions -Model "claude-sonnet-4-20250514" -MaxTurns 5
Invoke-Claude -Prompt "Help me debug this code" -Options $options

# Pipeline support
"Explain recursion" | Invoke-Claude -AsText

# Configuration management
Get-ClaudeSettings
Set-ClaudeSetting -Name "Model" -Value "claude-sonnet-4-20250514"

# Agent management
Get-ClaudeAgent
New-ClaudeAgent -Name "reviewer" -Instructions "Review code for quality"

# Command management
Get-ClaudeCommand
New-ClaudeCommand -Name "test" -PromptTemplate "Run tests for: $ARGS"

# MCP server management
Get-ClaudeMcpServer
Add-ClaudeMcpServer -Name "myserver" -Command "npx" -Args @("-y", "my-mcp-server")

Requirements

• .NET 10.0 or later
• PowerShell 7.4 or later (for PowerShell module)
• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)

Project Structure

ClaudeAgentSDK.NET/
├── src/
│   ├── ClaudeAgentSDK.NET/              # Core SDK
│   │   ├── Claude.cs                # Static API entry point
│   │   ├── ClaudeClient.cs          # Stateful client
│   │   ├── ClaudeOptions.cs         # Configuration options
│   │   ├── Messages/                # Message types
│   │   ├── Hooks/                   # Hook system
│   │   ├── Configuration/           # Settings, agents, commands, MCP
│   │   └── Internal/                # Transport, parsing
│   └── ClaudeAgentSDK.NET.PowerShell/   # PowerShell cmdlets
├── tests/
│   ├── ClaudeAgentSDK.NET.Tests/        # 108 unit/integration tests
│   └── ClaudeAgentSDK.NET.PowerShell.Tests/  # 3 cmdlet tests
└── examples/
    ├── CSharp/
    │   ├── QuickStart.cs            # Basic usage
    │   └── WithHooks.cs             # Hook examples
    └── PowerShell/
        ├── BasicUsage.ps1           # Basic cmdlet usage
        └── WithHooks.ps1            # Advanced patterns

API Reference

Core Classes

Message Types

Configuration Classes

PowerShell Cmdlets

Building

cd ClaudeAgentSDK.NET
dotnet restore
dotnet build
dotnet test

Release Build

dotnet build --configuration Release
dotnet test --configuration Release

Documentation

See the docs/ folder for detailed design documentation:

• 02-BUILD-PLAN.md - Implementation roadmap
• 03-TYPE-MAPPING.md - Type definitions
• 05-CONTROL-PROTOCOL.md - Bidirectional protocol
• 06-HOOK-SYSTEM.md - Hook system design
• 07-CONFIGURATION-MANAGEMENT.md - Configuration APIs

Known Limitations

• Hook callbacks are registered locally but require CLI bidirectional control protocol support for invocation (not available in --print mode)
• MCP message routing is a placeholder for future implementation

License

MIT License