Claude Code Go SDK

https://github.com/yukifoo/claude-code-sdk-go
Admin
A Go SDK for Claude Code that provides programmatic access to Claude's agentic coding capabilities,...
Tokens:9,547
Snippets:32
Trust Score:5.1
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run Quick Start Example (Go)

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Executes the primary quick start Go program to demonstrate fundamental SDK usage.

```bash
go run quick_start.go
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/advanced/README.md

Provides an example JSON structure for configuring MCP servers, detailing the command and arguments needed to start a specific server like the filesystem server.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}
```

--------------------------------

### Install Claude Code CLI

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Installs the Claude Code CLI globally using npm, a prerequisite for using the SDK.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Run the Go Example

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/advanced/README.md

Demonstrates how to execute the main Go program for the Claude Code SDK example. This command initiates the application to showcase its features.

```bash
go run main.go
```

--------------------------------

### Run Basic Examples (Go)

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Navigates to the basic examples directory and runs the main Go program for basic API usage.

```bash
cd basic && go run main.go
```

--------------------------------

### Verify Claude CLI

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Checks if the Claude CLI is installed and accessible by displaying its help information.

```bash
claude --help
```

--------------------------------

### Configure Custom System Prompts

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/advanced/README.md

Allows customization of the system prompt by providing an initial prompt or appending to an existing one. This guides the AI's behavior and response style.

```go
Options: &claudecode.Options{
    SystemPrompt:       stringPtr("You are a senior Go architect..."),
    AppendSystemPrompt: stringPtr("Always provide specific recommendations."),
}
```

--------------------------------

### Run Advanced Examples (Go)

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Navigates to the advanced examples directory and runs the main Go program demonstrating advanced SDK features.

```bash
cd advanced && go run main.go
```

--------------------------------

### Run Streaming Examples (Go)

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Navigates to the streaming examples directory and runs the main Go program for real-time message processing.

```bash
cd streaming && go run main.go
```

--------------------------------

### Run Go Streaming Example

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/streaming/README.md

Executes the main Go program to demonstrate the Claude Code SDK's streaming features, including file operations and project analysis.

```bash
go run main.go
```

--------------------------------

### Claude Code SDK Go Session Management Examples

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Demonstrates how to manage conversation sessions using the Claude Code SDK. This includes starting a new session, retrieving its ID, resuming a specific session using its ID, and continuing the most recent session.

```go
// Start a session and get session ID
messages, err := claudecode.QueryWithRequest(ctx, claudecode.QueryRequest{
    Prompt: "Create a function",
    Options: &claudecode.Options{
        OutputFormat: outputFormatPtr(claudecode.OutputFormatJSON),
    },
})

// Extract session ID from result message
var sessionID string
for _, msg := range messages {
    if result, ok := msg.(*claudecode.ResultMessage); ok {
        // Parse session ID from result
        // sessionID = ... 
    }
}

// Resume the session
claudecode.QueryWithRequest(ctx, claudecode.QueryRequest{
    Prompt: "Add tests for that function",
    Options: &claudecode.Options{
        Resume: &sessionID,
    },
})

// Or continue the latest session
claudecode.QueryWithRequest(ctx, claudecode.QueryRequest{
    Prompt: "Optimize the code",
    Options: &claudecode.Options{
        Continue: boolPtr(true),
    },
})
```

--------------------------------

### Update Go Modules

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Ensures Go module dependencies are up-to-date and correctly managed for the project.

```bash
go mod tidy
```

--------------------------------

### Authenticate Claude CLI

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Initiates the authentication process for the Claude CLI, typically by running the command without arguments.

```bash
claude
```

--------------------------------

### Configure MCP Integration

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/advanced/README.md

Sets up Model Context Protocol (MCP) server integration, specifying allowed tools and a permission prompt tool. This configuration is crucial for enabling external protocol interactions.

```go
Options: &claudecode.Options{
    MCPConfig:           stringPtr("mcp-servers.json"),
    AllowedTools:        []string{"mcp__filesystem__read_file"},
    PermissionPromptTool: stringPtr("mcp__permissions__approve")
}
```

--------------------------------

### Configure Session Management

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/advanced/README.md

Demonstrates how to resume a specific session or continue the latest conversation using session management features. This allows for stateful interactions and persistent context.

```go
Options: &claudecode.Options{
    Resume:   stringPtr("session-id"),     // Resume specific session
    Continue: boolPtr(true),               // Continue latest session
}
```

--------------------------------

### Claude Code Go Development Commands

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/CLAUDE.md

Common development commands for the Go SDK, including testing, building, formatting, linting, and running examples.

```APIDOC
Development Commands:

# Run all tests
go test -v

# Run tests with coverage
go test -v -cover

# Run specific test
go test -v -run TestOptions

# Run only unit tests (skip integration tests)
go test -v -short

# Build the module
go build

# Format and vet
go fmt ./...
go vet ./...

# Lint with golangci-lint (recommended for Go Report Card compliance)
golangci-lint run

# Install golangci-lint (if not already installed)
# macOS: brew install golangci-lint
# Linux: curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
# Windows: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Test examples (requires authenticated claude CLI)
cd examples/basic && go run main.go
cd examples/streaming && go run main.go
cd examples/advanced && go run main.go

# Verify Claude CLI availability
claude --help
```

--------------------------------

### Claude Code SDK Go API Usage

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/README.md

Demonstrates the two primary ways to interact with the Claude Code SDK in Go: the new request-based API and the traditional prompt-based API.

```APIDOC
New API (TypeScript/Python Compatible):
  request := claudecode.QueryRequest{
      Prompt: "Create a function",
      Options: &claudecode.Options{...},
  }
  messages, err := claudecode.QueryWithRequest(ctx, request)

Traditional API (Backward Compatible):
  messages, err := claudecode.Query(ctx, prompt, options)
```

--------------------------------

### Configure Tool Restrictions

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/examples/advanced/README.md

Applies restrictions on available tools by specifying explicitly allowed and disallowed tools. This enhances security and controls the execution environment.

```go
Options: &claudecode.Options{
    AllowedTools:    []string{"Read", "LS", "Grep"},
    DisallowedTools: []string{"Write", "Bash"},
}
```

--------------------------------

### Claude Code SDK Go MCP Integration Example

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Illustrates how to integrate with Model Context Protocol (MCP) servers. This involves configuring MCP servers in a JSON file and specifying allowed MCP tools and permission prompt tools within the SDK options.

```json
// mcp-servers.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}
```

```go
// Use MCP tools
request := claudecode.QueryRequest{
    Prompt: "Analyze project files",
    Options: &claudecode.Options{
        MCPConfig:    stringPtr("mcp-servers.json"),
        AllowedTools: []string{"mcp__filesystem__read_file", "mcp__filesystem__list_directory"},
        PermissionPromptTool: stringPtr("mcp__permissions__approve"),
    },
}
```

--------------------------------

### Claude Code SDK Go Tool Restriction Example

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Shows how to restrict the tools available to Claude. This is achieved by providing lists of `AllowedTools` and `DisallowedTools` within the `Options` struct, enabling fine-grained control over tool execution.

```go
options := &claudecode.Options{
    AllowedTools:    []string{"Read", "LS", "Grep"},     // Only these tools
    DisallowedTools: []string{"Bash", "Write"},          // Block these tools
}
```

--------------------------------

### Claude Code SDK Go Error Handling

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Provides an example of how to handle various error types returned by the Claude Code SDK. It uses a type switch to differentiate between specific errors like `CLINotFoundError`, `ProcessError`, `CLIConnectionError`, and `CLIJSONDecodeError`.

```go
if err != nil {
    switch e := err.(type) {
    case *claudecode.CLINotFoundError:
        fmt.Printf("Claude CLI not found: %v\n", e)
    case *claudecode.ProcessError:
        fmt.Printf("CLI process error (exit %d): %s\n", e.ExitCode, e.Stderr)
    case *claudecode.CLIConnectionError:
        fmt.Printf("Connection error: %v\n", e)
    case *claudecode.CLIJSONDecodeError:
        fmt.Printf("JSON decode error: %v\n", e)
    default:
        fmt.Printf("Unknown error: %v\n", e)
    }
}
```

--------------------------------

### Development Commands for Claude Code SDK

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Provides essential bash commands for developing and testing the Claude Code SDK for Go. This includes running tests with various flags (verbose, coverage, short for unit tests) and building the project. Integration tests require an authenticated Claude CLI.

```bash
# Run all tests
go test -v
```

```bash
# Run tests with coverage
go test -v -cover
```

```bash
# Run only unit tests (skip integration tests)
go test -v -short
```

```bash
# Run specific test
go test -v -run TestOptions
```

```bash
# Build the project
go build
```

```bash
# Ensure Claude CLI is working
claude --help
```

```bash
# Run integration tests
go test -v
```

--------------------------------

### Basic Query with Claude Code SDK in Go

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Demonstrates basic programmatic interaction with the Claude Code SDK using the `QueryRequest` structure. This method sends a prompt and options to Claude Code and returns the processed messages, mirroring patterns found in TypeScript and Python SDKs.

```go
package main

import (
    "context"
    "fmt"
    "log"
    
    claudecode "github.com/yukifoo/claude-code-sdk-go"
)

func main() {
    ctx := context.Background()
    
    // Create a request using the TypeScript/Python SDK compatible format
    request := claudecode.QueryRequest{
        Prompt: "Create a simple hello.go file that prints 'Hello, World!'",
        Options: &claudecode.Options{
            MaxTurns:     intPtr(3),
            AllowedTools: []string{"Read", "Write"},
            SystemPrompt: stringPtr("You are a helpful Go programming assistant"),
        },
    }
    
    messages, err := claudecode.QueryWithRequest(ctx, request)
    if err != nil {
        log.Fatalf("Query failed: %v", err)
    }
    
    fmt.Printf("Received %d messages\n", len(messages))
    for _, message := range messages {
        fmt.Printf("Message type: %s\n", message.Type())
        for _, block := range message.Content() {
            if textBlock, ok := block.(*claudecode.TextBlock); ok {
                fmt.Printf("Content: %s\n", textBlock.Text)
            }
        }
    }
}

func intPtr(i int) *int { return &i }
func stringPtr(s string) *string { return &s }
```

--------------------------------

### Claude Code SDK Go API Compatibility Styles

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Compares the two API styles supported by the Claude Code SDK for Go: the recommended single-object parameter style, similar to TypeScript/Python SDKs, and the traditional multi-parameter Go API.

```go
// Single object parameter like TypeScript/Python SDKs
claudecode.QueryWithRequest(ctx, claudecode.QueryRequest{
    Prompt: "...",
    Options: &claudecode.Options{...},
})

claudecode.QueryStreamWithRequest(ctx, claudecode.QueryRequest{
    Prompt: "...",
    Options: &claudecode.Options{...},
})
```

```go
// Multiple parameters (original API)
claudecode.Query(ctx, prompt, options)
claudecode.QueryStream(ctx, prompt, options)
```

--------------------------------

### Claude Code SDK Go Options Struct

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Defines the `Options` struct for configuring the Claude Code CLI behavior. It includes settings for system prompts, conversation limits, tool usage, session management, output formats, MCP integration, and system-level configurations.

```go
type Options struct {
    // System prompts
    SystemPrompt       *string           // Custom system prompt
    AppendSystemPrompt *string           // Append to default system prompt
    
    // Conversation control
    MaxTurns           *int              // Limit conversation turns
    
    // Tool configuration
    AllowedTools       []string          // Tools Claude can use
    DisallowedTools    []string          // Tools Claude cannot use
    
    // Session management
    Resume             *string           // Resume session by ID
    Continue           *bool             // Continue latest session
    
    // Output and logging
    OutputFormat       *OutputFormat     // text, json, stream-json
    Verbose            *bool             // Enable verbose logging
    
    // MCP (Model Context Protocol)
    MCPConfig          *string           // Path to MCP config JSON
    PermissionPromptTool *string         // MCP tool for permissions
    
    // System
    WorkingDirectory   *string           // Working directory
    Executable         *string           // Custom CLI path
}
```

--------------------------------

### Go SDK API Functions for Claude Code CLI

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/CLAUDE.md

Provides Go functions to interact with the Claude Code CLI, supporting both new request-based and traditional prompt-based APIs, including streaming.

```go
package claude

import (
	"context"
	"io"
)

// QueryRequest represents the parameters for a new API query.
type QueryRequest struct {
	Prompt  string
	Options Options
}

// QueryWithRequest sends a request using the new API pattern.
// It returns the response content and an error.
func QueryWithRequest(ctx context.Context, req QueryRequest) (string, error) {
	// Implementation details...
	return "", nil
}

// QueryStreamWithRequest streams responses using the new API pattern.
// It returns a channel for content blocks and an error.
func QueryStreamWithRequest(ctx context.Context, req QueryRequest) (<-chan ContentBlock, error) {
	// Implementation details...
	return nil, nil
}

// Query sends a request using the traditional API pattern.
// It returns the response content and an error.
func Query(ctx context.Context, prompt string, options Options) (string, error) {
	// Implementation details...
	return "", nil
}

// QueryStream streams responses using the traditional API pattern.
// It returns a channel for content blocks and an error.
func QueryStream(ctx context.Context, prompt string, options Options) (<-chan ContentBlock, error) {
	// Implementation details...
	return nil, nil
}

// Placeholder for Options struct and ContentBlock interface
type Options struct {}
type ContentBlock interface { Type() string }
```

--------------------------------

### Streaming Query with Claude Code SDK in Go

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Illustrates how to perform streaming queries with the Claude Code SDK, enabling real-time processing of responses via Go channels. This is useful for interactive applications or when dealing with large, incremental outputs from Claude Code.

```go
package main

import (
    "context"
    "fmt"
    "log"
    
    claudecode "github.com/yukifoo/claude-code-sdk-go"
)

func main() {
    ctx := context.Background()
    
    request := claudecode.QueryRequest{
        Prompt: "Analyze this Go project and suggest improvements",
        Options: &claudecode.Options{
            AllowedTools: []string{"Read", "LS", "Grep"},
            OutputFormat: outputFormatPtr(claudecode.OutputFormatStreamJSON),
            Verbose:      boolPtr(true),
        },
    }
    
    messageChan, errorChan := claudecode.QueryStreamWithRequest(ctx, request)
    
    for {
        select {
        case message, ok := <-messageChan:
            if !ok {
                fmt.Println("Streaming completed")
                return
            }
            
            fmt.Printf("Received %s message\n", message.Type())
            // Process message...
            
        case err := <-errorChan:
            if err != nil {
                log.Fatalf("Streaming error: %v", err)
            }
            
        case <-ctx.Done():
            fmt.Println("Context cancelled")
            return
        }
    }
}

func boolPtr(b bool) *bool { return &b }
func outputFormatPtr(f claudecode.OutputFormat) *claudecode.OutputFormat { return &f }
```

--------------------------------

### Handling Claude Code Message Types in Go

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Demonstrates how to iterate through messages received from the Claude Code SDK and process different content blocks like text and tool uses. It requires the `claudecode` package.

```go
for _, message := range messages {
    switch msg := message.(type) {
    case *claudecode.AssistantMessage:
        fmt.Println("Assistant response")
    case *claudecode.UserMessage:
        fmt.Println("User message")
    case *claudecode.SystemMessage:
        fmt.Println("System message")
    case *claudecode.ResultMessage:
        fmt.Println("Final result")
    }
    
    // Process content blocks
    for _, block := range message.Content() {
        switch b := block.(type) {
        case *claudecode.TextBlock:
            fmt.Printf("Text: %s\n", b.Text)
        case *claudecode.ToolUseBlock:
            fmt.Printf("Tool: %s\n", b.Name)
        case *claudecode.ToolResultBlock:
            fmt.Printf("Result: %v\n", b.Content)
        }
    }
}
```

--------------------------------

### Claude Code SDK Go Output Formats

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/README.md

Lists the available output format constants for the Claude Code SDK. These constants specify how the output from the Claude CLI should be processed, including plain text, structured JSON, and streaming JSON.

```go
// Available output formats
claudecode.OutputFormatText       // Plain text (default for Query)
claudecode.OutputFormatJSON       // Structured JSON
claudecode.OutputFormatStreamJSON // Streaming JSON (default for QueryStream)
```

--------------------------------

### Translate Go Structs to CLI Arguments

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/CLAUDE.md

The `buildCommandArgs()` function translates Go struct fields into command-line arguments for the Claude CLI. It handles pointer fields as optional flags, array fields as space-separated arguments, and maps struct field names to specific CLI flags, including special handling for output format and verbose flag dependencies.

```go
func buildCommandArgs(config interface{}) ([]string, error) {
    // ... implementation details ...
    // Handles pointer fields (*string, *int, *bool) as optional CLI flags
    // Handles array fields ([]string) as space-separated arguments
    // Maps field names like Cwd to --cwd, SystemPrompt to --system-prompt
    // Special handling for output format and verbose flag dependencies
    return args, nil
}
```

--------------------------------

### Go SDK API Compatibility with Other SDKs

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/CLAUDE.md

The Go SDK maintains strict API compatibility with TypeScript and Python SDKs. This includes mirroring the `QueryRequest` struct pattern, using Go pointer types for optional fields, matching field names and ordering, and supporting all CLI options from official SDKs.

```APIDOC
API Compatibility:

- QueryRequest struct mirrors `{prompt, options}` pattern.
- Options fields use Go pointer types to distinguish unset from zero values.
- Field names and ordering match official SDKs (e.g., AllowedTools, SystemPrompt, Cwd).
- All CLI options from official SDKs are supported, plus additional CLI-documented options.
- Message/ContentBlock interfaces provide identical type hierarchy with matching field names.
- Message structures include all official SDK fields (e.g., parent_tool_use_id, session_id, usage data).
- Environment variable CLAUDE_CODE_ENTRYPOINT=sdk-go matches official SDK pattern.
- Error handling patterns mirror Python SDK error classes.
- Function signatures support both Go patterns and cross-language consistency.
```

--------------------------------

### Claude CLI Error Context Strategies

Source: https://github.com/yukifoo/claude-code-sdk-go/blob/main/CLAUDE.md

The SDK defines specific error types to capture different failure modes when interacting with the Claude CLI. These include errors for CLI unavailability, execution failures with exit codes and stderr, I/O pipe issues, and JSON decoding problems.

```go
type CLINotFoundError struct { /* ... */ }
// Error: Claude CLI not available

type ProcessError struct {
    ExitCode int
    Stderr   string
    // ... other fields ...
}
// Error: CLI execution failure with exit codes and stderr

type CLIConnectionError struct { /* ... */ }
// Error: I/O pipe failures

type CLIJSONDecodeError struct {
    RawData string
    // ... other fields ...
}
// Error: JSON parsing failures with raw data context
```
Tokens:
Raw