@spec available_presets() :: [atom()]

Lists all available preset names.

Useful for dynamic configuration or validation.

Examples

presets = ClaudeCodeSDK.OptionBuilder.available_presets()
# => [:development, :staging, :production, :analysis, :chat, :documentation, :testing]

@spec build_analysis_options() :: ClaudeCodeSDK.Options.t()

Builds options optimized for code analysis tasks.

Use for: Code reviews, security audits, quality analysis

Features:

• Read and search tools for thorough analysis
• Higher turn limit (7) for comprehensive review
• No modification permissions for safety
• Specialized system prompt for analysis focus

Examples

options = ClaudeCodeSDK.OptionBuilder.build_analysis_options()
ClaudeCodeSDK.query("Review this module for potential issues", options)

@spec build_chat_options() :: ClaudeCodeSDK.Options.t()

Builds options for simple chat and Q&A interactions.

Use for: Help desk, documentation queries, general assistance

Features:

• Single turn for quick responses
• Text output for simple display
• No tool access to prevent unintended actions
• Minimal permissions

Examples

options = ClaudeCodeSDK.OptionBuilder.build_chat_options()
ClaudeCodeSDK.query("What is the difference between async and sync?", options)

@spec build_development_options() :: ClaudeCodeSDK.Options.t()

Builds options suitable for development environment.

Use for: Local development, debugging, experimentation

Features:

• Higher turn limit (10) for complex tasks
• Verbose output for debugging
• All tools allowed for full functionality
• Edit permissions accepted for rapid iteration
• Stream JSON output for real-time feedback

Examples

# Basic development setup
options = ClaudeCodeSDK.OptionBuilder.build_development_options()
ClaudeCodeSDK.query("Help me debug this function", options)

# Development with custom system prompt
options = 
  ClaudeCodeSDK.OptionBuilder.build_development_options()
  |> ClaudeCodeSDK.OptionBuilder.with_system_prompt("You are a debugging expert")

@spec build_documentation_options() :: ClaudeCodeSDK.Options.t()

Builds options for documentation generation tasks.

Use for: API docs, README generation, code documentation

Features:

• Read access to understand existing code
• Write access for creating documentation files
• Higher turn limit (8) for comprehensive docs
• Accept edits mode for file creation
• Specialized prompt for documentation focus

Examples

options = ClaudeCodeSDK.OptionBuilder.build_documentation_options()
ClaudeCodeSDK.query("Generate API documentation for this module", options)

@spec build_production_options() :: ClaudeCodeSDK.Options.t()

Builds options suitable for production environment.

Use for: Production monitoring, read-only analysis, customer-facing features

Features:

• Low turn limit (3) for efficiency
• Read-only access only
• Plan mode for safety
• Minimal tool access
• Structured JSON output

Examples

# Production-safe code analysis
options = ClaudeCodeSDK.OptionBuilder.build_production_options()
ClaudeCodeSDK.query("Explain what this function does", options)

@spec build_staging_options() :: ClaudeCodeSDK.Options.t()

Builds options suitable for staging/testing environment.

Use for: CI/CD pipelines, automated testing, code review

Features:

• Moderate turn limit (5) for focused tasks
• Read-only tools for safety
• Plan mode prevents automatic changes
• Bash disabled to prevent system modifications
• JSON output for structured results

Examples

# Use in CI for code analysis
options = ClaudeCodeSDK.OptionBuilder.build_staging_options()
ClaudeCodeSDK.query("Analyze this code for security issues", options)

@spec build_testing_options() :: ClaudeCodeSDK.Options.t()

Builds options for test generation and testing tasks.

Use for: Unit test creation, test analysis, quality assurance

Features:

• Read access to understand code under test
• Write access for creating test files
• Moderate turn limit for thorough test coverage
• Testing-focused system prompt

Examples

options = ClaudeCodeSDK.OptionBuilder.build_testing_options()
ClaudeCodeSDK.query("Generate comprehensive unit tests for this module", options)

@spec for_environment() :: ClaudeCodeSDK.Options.t()

Builds options for a specific environment based on Mix.env().

Automatically selects appropriate options based on current environment:

• :dev -> development options (permissive, verbose)
• :test -> staging options (moderate restrictions)
• :prod -> production options (restrictive, safe)

This is the recommended way to get environment-appropriate defaults.

Examples

# Get options for current environment
options = ClaudeCodeSDK.OptionBuilder.for_environment()

# In development, this gives you full access
# In production, this gives you read-only access

@spec merge(atom() | ClaudeCodeSDK.Options.t(), map()) :: ClaudeCodeSDK.Options.t()

Merges custom options with a base configuration.

Allows you to start with a preset and customize specific fields. This is the recommended pattern for customizing presets.

Parameters

• base - Base preset (atom) or Options struct
• custom - Map of custom options to override

Examples

# Start with development preset, customize turn limit
options = ClaudeCodeSDK.OptionBuilder.merge(:development, %{max_turns: 15})

# Start with analysis preset, add custom prompt
options = ClaudeCodeSDK.OptionBuilder.merge(:analysis, %{
  system_prompt: "Focus on security vulnerabilities",
  max_turns: 10
})

# Merge with existing options
base_options = ClaudeCodeSDK.OptionBuilder.build_chat_options()
options = ClaudeCodeSDK.OptionBuilder.merge(base_options, %{max_turns: 3})

@spec quick() :: ClaudeCodeSDK.Options.t()

Creates options for quick, one-off queries.

Use for: Simple questions, quick checks, lightweight operations

Features:

• Single turn limit
• Text output for simplicity
• No tools for safety
• Fast response

Examples

options = ClaudeCodeSDK.OptionBuilder.quick()
ClaudeCodeSDK.query("What does this error mean?", options)

@spec sandboxed(String.t(), [String.t()]) :: ClaudeCodeSDK.Options.t()

Creates a sandboxed configuration for safe execution.

Use for: Untrusted code execution, isolated environments, testing

Features:

• Isolated to specific directory
• Bypass permissions (safe within sandbox)
• Customizable tool access
• No bash access by default

Parameters

• sandbox_path - Path to sandbox directory
• allowed_tools - List of tools to allow (default: ["Read", "Write"])

Examples

# Basic sandbox
options = ClaudeCodeSDK.OptionBuilder.sandboxed("/tmp/sandbox")

# Sandbox with custom tools
options = ClaudeCodeSDK.OptionBuilder.sandboxed("/tmp/safe", ["Read", "Write", "Grep"])

@spec validate(ClaudeCodeSDK.Options.t()) ::
  {:ok, ClaudeCodeSDK.Options.t()}
  | {:warning, ClaudeCodeSDK.Options.t(), [String.t()]}
  | {:error, String.t()}

Validates that an options struct has sensible configuration.

Checks for common misconfigurations and provides warnings.

Parameters

• options - Options struct to validate

Returns

• {:ok, options} if valid
• {:warning, options, warnings} if valid but has warnings
• {:error, reason} if invalid

Examples

options = ClaudeCodeSDK.OptionBuilder.build_development_options()
{:ok, _} = ClaudeCodeSDK.OptionBuilder.validate(options)

@spec with_additional_tools(ClaudeCodeSDK.Options.t(), [String.t()]) ::
  ClaudeCodeSDK.Options.t()

Adds additional allowed tools to any options.

Parameters

• options - Options struct to modify
• tools - List of additional tools to allow

Examples

options = 
  ClaudeCodeSDK.OptionBuilder.build_production_options()
  |> ClaudeCodeSDK.OptionBuilder.with_additional_tools(["Grep"])

@spec with_agent(ClaudeCodeSDK.Options.t(), String.t(), map()) ::
  ClaudeCodeSDK.Options.t()

Adds custom agent to options.

Examples

options = OptionBuilder.build_development_options()
|> OptionBuilder.with_agent("security_reviewer", %{
  description: "Security-focused code reviewer",
  prompt: "You are a security expert. Review for vulnerabilities."
})

@spec with_agents(map()) :: ClaudeCodeSDK.Options.t()

Sets multiple agents at once.

Examples

agents = %{
  "reviewer" => %{description: "Code reviewer", prompt: "Review code"},
  "tester" => %{description: "Test generator", prompt: "Generate tests"}
}

options = OptionBuilder.with_agents(agents)

@spec with_haiku() :: ClaudeCodeSDK.Options.t()

Builds options for fast responses using Haiku model.

Best for:

• Simple queries
• Quick responses needed
• High-volume use cases
• Lowest cost option

Examples

options = ClaudeCodeSDK.OptionBuilder.with_haiku()
ClaudeCodeSDK.query("What is 2+2?", options)

@spec with_model(ClaudeCodeSDK.Options.t(), String.t(), String.t() | nil) ::
  ClaudeCodeSDK.Options.t()

Adds specific model to any options.

Parameters

• options - Existing options
• model_name - Model name ("opus", "sonnet", "haiku", or full name like "claude-sonnet-4-5-20250929")
• fallback - Optional fallback model

Examples

options = build_development_options()
|> with_model("opus", "sonnet")

@spec with_opus() :: ClaudeCodeSDK.Options.t()

Builds options for maximum capability using Opus model.

Best for:

• Complex reasoning tasks
• Code generation requiring deep understanding
• Multi-step problem solving

Higher cost but better results.

Examples

options = ClaudeCodeSDK.OptionBuilder.with_opus()
ClaudeCodeSDK.query("Architect a complex system", options)

@spec with_sonnet() :: ClaudeCodeSDK.Options.t()

Builds options for balanced performance using Sonnet model (default).

Best for:

• General-purpose tasks
• Good balance of speed and capability
• Most cost-effective for production

Examples

options = ClaudeCodeSDK.OptionBuilder.with_sonnet()
ClaudeCodeSDK.query("Review this code", options)

@spec with_system_prompt(String.t()) :: ClaudeCodeSDK.Options.t()

Adds a custom system prompt to any options.

Parameters

• prompt - System prompt to use
• options - Options struct to modify (optional, creates new if not provided)

Examples

options = ClaudeCodeSDK.OptionBuilder.with_system_prompt("You are a security expert")

options = 
  ClaudeCodeSDK.OptionBuilder.build_analysis_options()
  |> ClaudeCodeSDK.OptionBuilder.with_system_prompt("You are a security expert")

@spec with_turn_limit(ClaudeCodeSDK.Options.t(), pos_integer()) ::
  ClaudeCodeSDK.Options.t()

Sets a custom turn limit for any options.

Parameters

• options - Options struct to modify
• turns - Maximum number of turns

Examples

options = 
  ClaudeCodeSDK.OptionBuilder.build_chat_options()
  |> ClaudeCodeSDK.OptionBuilder.with_turn_limit(5)

@spec with_working_directory(String.t()) :: ClaudeCodeSDK.Options.t()

Adds a custom working directory to any options.

Parameters

• cwd - Working directory path
• options - Options struct to modify (optional, creates new if not provided)

Examples

options = ClaudeCodeSDK.OptionBuilder.with_working_directory("/project")

options = 
  ClaudeCodeSDK.OptionBuilder.build_development_options()
  |> ClaudeCodeSDK.OptionBuilder.with_working_directory("/project")