Key Features

Two APIs for different needs - Query for automation, Client for interaction 100% Python SDK compatibility - Same functionality, Go-native design Automatic resource management - WithClient provides Go-idiomatic context manager pattern Session management - Isolated conversation contexts with Query() and QueryWithSession() Built-in tool integration - File operations, AWS, GitHub, databases, and more Production ready - Comprehensive error handling, timeouts, resource cleanup Security focused - Granular tool permissions and access controls Context-aware - Maintain conversation state across multiple interactions Advanced capabilities - Permission callbacks, lifecycle hooks, file checkpointing

Usage

Query API - One-Shot Operations

Best for automation, scripting, and tasks with clear completion criteria:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/severity1/claude-agent-sdk-go"
)

func main() {
    fmt.Println("Claude Agent SDK - Query API Example")
    fmt.Println("Asking: What is 2+2?")

    ctx := context.Background()

    // Create and execute query
    iterator, err := claudecode.Query(ctx, "What is 2+2?")
    if err != nil {
        // Use error type helpers for specific error handling
        if cliErr := claudecode.AsCLINotFoundError(err); cliErr != nil {
            fmt.Printf("Claude CLI not found: %v\n", cliErr)
            fmt.Println("Install with: npm install -g @anthropic-ai/claude-code")
            return
        }
        if connErr := claudecode.AsConnectionError(err); connErr != nil {
            fmt.Printf("Connection failed: %v\n", connErr)
            return
        }
        log.Fatalf("Query failed: %v", err)
    }
    defer iterator.Close()

    fmt.Println("\nResponse:")

    // Iterate through messages
    for {
        message, err := iterator.Next(ctx)
        if err != nil {
            if errors.Is(err, claudecode.ErrNoMoreMessages) {
                break
            }
            log.Fatalf("Failed to get message: %v", err)
        }

        if message == nil {
            break
        }

        // Handle different message types
        switch msg := message.(type) {
        case *claudecode.AssistantMessage:
            for _, block := range msg.Content {
                if textBlock, ok := block.(*claudecode.TextBlock); ok {
                    fmt.Print(textBlock.Text)
                }
            }
        case *claudecode.ResultMessage:
            if msg.IsError {
                if msg.Result != nil {
                    log.Printf("Error: %s", *msg.Result)
                } else {
                    log.Printf("Error: unknown error")
                }
            }
        }
    }

    fmt.Println("\nQuery completed!")
}

Client API - Interactive & Multi-Turn

WithClient provides automatic resource management (equivalent to Python's async with):

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/severity1/claude-agent-sdk-go"
)

func main() {
    fmt.Println("Claude Agent SDK - Client Streaming Example")
    fmt.Println("Asking: Explain Go goroutines with a simple example")

    ctx := context.Background()
    question := "Explain what Go goroutines are and show a simple example"

    // WithClient handles connection lifecycle automatically
    err := claudecode.WithClient(ctx, func(client claudecode.Client) error {
        fmt.Println("\nConnected! Streaming response:")

        // Simple query uses default session
        if err := client.Query(ctx, question); err != nil {
            return fmt.Errorf("query failed: %w", err)
        }

        // Stream messages in real-time
        msgChan := client.ReceiveMessages(ctx)
        for {
            select {
            case message := <-msgChan:
                if message == nil {
                    return nil // Stream ended
                }

                switch msg := message.(type) {
                case *claudecode.AssistantMessage:
                    // Print streaming text as it arrives
                    for _, block := range msg.Content {
                        if textBlock, ok := block.(*claudecode.TextBlock); ok {
                            fmt.Print(textBlock.Text)
                        }
                    }
                case *claudecode.ResultMessage:
                    if msg.IsError {
                        if msg.Result != nil {
                            return fmt.Errorf("error: %s", *msg.Result)
                        }
                        return fmt.Errorf("error: unknown error")
                    }
                    return nil // Success, stream complete
                }
            case <-ctx.Done():
                return ctx.Err()
            }
        }
    })

    if err != nil {
        log.Fatalf("Streaming failed: %v", err)
    }

    fmt.Println("\n\nStreaming completed!")
}

Session Management

Maintain conversation context across multiple queries with session management:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/severity1/claude-agent-sdk-go"
)

func main() {
    fmt.Println("Claude Agent SDK - Session Management Example")

    ctx := context.Background()

    err := claudecode.WithClient(ctx, func(client claudecode.Client) error {
        fmt.Println("\nDemonstrating isolated sessions:")

        // Session A: Math conversation
        sessionA := "math-session"
        if err := client.QueryWithSession(ctx, "Remember this: x = 5", sessionA); err != nil {
            return err
        }

        // Session B: Programming conversation
        sessionB := "programming-session"
        if err := client.QueryWithSession(ctx, "Remember this: language = Go", sessionB); err != nil {
            return err
        }

        // Query each session - they maintain separate contexts
        fmt.Println("\nQuerying math session:")
        if err := client.QueryWithSession(ctx, "What is x * 2?", sessionA); err != nil {
            return err
        }

        fmt.Println("\nQuerying programming session:")
        if err := client.QueryWithSession(ctx, "What language did I mention?", sessionB); err != nil {
            return err
        }

        // Default session query (separate from above)
        fmt.Println("\nDefault session (no context from above):")
        return client.Query(ctx, "What did I just ask about?") // Won't know about x or Go
    })

    if err != nil {
        log.Fatalf("Session demo failed: %v", err)
    }

    fmt.Println("Session management demo completed!")
}

Traditional Client API (still supported):

func traditionalClientExample() {
    ctx := context.Background()
    
    client := claudecode.NewClient()
    if err := client.Connect(ctx); err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer client.Disconnect() // Manual cleanup required
    
    // Use client...
}

Tool Integration & External Services

Integrate with file systems, cloud services, databases, and development tools:

Core Tools (built-in file operations):

// File analysis and documentation generation
claudecode.Query(ctx, "Read all Go files and create API documentation",
    claudecode.WithAllowedTools("Read", "Write"))

MCP Tools (external service integrations):

// AWS infrastructure automation
claudecode.Query(ctx, "List my S3 buckets and analyze their security settings",
    claudecode.WithAllowedTools("mcp__aws-api-mcp__call_aws", "mcp__aws-api-mcp__suggest_aws_commands", "Write"))

Configuration Options

Customize Claude's behavior with functional options:

Tool & Permission Control:

claudecode.Query(ctx, prompt,
    claudecode.WithAllowedTools("Read", "Write"),
    claudecode.WithPermissionMode(claudecode.PermissionModeAcceptEdits))

System Behavior:

claudecode.Query(ctx, prompt,
    claudecode.WithSystemPrompt("You are a senior Go developer"),
    claudecode.WithModel("claude-sonnet-4-5"),
    claudecode.WithMaxTurns(10))

Environment Variables (new in v0.2.5):

// Proxy configuration
claudecode.N