ClaudeCode.Options (ClaudeCode v0.1.0)
View SourceHandles option validation and CLI flag conversion.
This module is the single source of truth for all ClaudeCode options. It provides validation for session and query options using NimbleOptions, converts Elixir options to CLI flags, and manages option precedence: query > session > app config > defaults.
Session Options
Session options are used when starting a ClaudeCode session. Most options can be overridden at the query level.
Required Options
:api_key
- Anthropic API key (string, required)
Claude Configuration
:model
- Claude model to use (string, optional - CLI uses its default):system_prompt
- Override system prompt (string, optional):append_system_prompt
- Append to system prompt (string, optional):max_turns
- Limit agentic turns in non-interactive mode (integer, optional)
Tool Control
:allowed_tools
- List of allowed tools (list of strings, optional) Example:["View", "Bash(git:*)"]
:disallowed_tools
- List of denied tools (list of strings, optional):add_dir
- Additional directories for tool access (list of strings, optional) Example:["/tmp", "/var/log"]
Advanced Options
:mcp_config
- Path to MCP servers JSON config file (string, optional):permission_prompt_tool
- MCP tool for handling permission prompts (string, optional):permission_mode
- Permission handling mode (atom, default: :default) Options::default
,:accept_edits
,:bypass_permissions
Elixir-Specific Options
:name
- GenServer process name (atom, optional):timeout
- Query timeout in milliseconds (timeout, default: 300_000) - Elixir only, not passed to CLI:permission_handler
- Custom permission handler module (atom, optional):cwd
- Current working directory (string, optional)
Query Options
Query options can override session defaults for individual queries.
All session options except :api_key
, :name
, and :permission_handler
can be used as query options.
Option Precedence
Options are resolved in this order (highest to lowest priority):
- Query-level options
- Session-level options
- Application configuration
- Schema defaults
Usage Examples
# Session with comprehensive options
{:ok, session} = ClaudeCode.start_link(
api_key: "sk-ant-...",
model: "opus",
system_prompt: "You are an Elixir expert",
allowed_tools: ["View", "Edit", "Bash(git:*)"],
add_dir: ["/tmp", "/var/log"],
max_turns: 20,
timeout: 180_000,
permission_mode: :default
)
# Query with option overrides
ClaudeCode.query_sync(session, "Help with testing",
system_prompt: "Focus on ExUnit patterns",
allowed_tools: ["View"],
timeout: 60_000
)
# Application configuration
# config/config.exs
config :claude_code,
model: "sonnet",
timeout: 120_000,
allowed_tools: ["View", "Edit"]
Security Considerations
:permission_mode
: Controls permission handling behavior. Use:bypass_permissions
only in development environments.:add_dir
: Grants tool access to additional directories. Only include safe directories.:allowed_tools
: Use tool restrictions to limit Claude's capabilities. Example:["View", "Bash(git:*)"]
allows read-only operations and git commands.
Summary
Functions
Applies application config defaults to session options.
Gets application configuration for claude_code.
Merges session and query options with query taking precedence.
Returns the query options schema.
Resolves final options using complete precedence chain.
Returns the session options schema.
Converts Elixir options to CLI arguments.
Validates query options using NimbleOptions.
Validates session options using NimbleOptions.
Functions
Applies application config defaults to session options.
Session options take precedence over app config.
Gets application configuration for claude_code.
Returns only valid option keys from the session schema.
Merges session and query options with query taking precedence.
Examples
iex> session_opts = [timeout: 60_000, model: "sonnet"]
iex> query_opts = [timeout: 120_000]
iex> ClaudeCode.Options.merge_options(session_opts, query_opts)
[model: "sonnet", timeout: 120_000]
Returns the query options schema.
Resolves final options using complete precedence chain.
Precedence: query > session > app config > defaults
Returns the session options schema.
Converts Elixir options to CLI arguments.
Ignores internal options like :api_key, :name, :timeout, and :permission_handler that are not CLI flags.
Examples
iex> ClaudeCode.Options.to_cli_args([system_prompt: "You are helpful"])
["--system-prompt", "You are helpful"]
iex> ClaudeCode.Options.to_cli_args([allowed_tools: ["View", "Bash(git:*)"]])
["--allowedTools", "View,Bash(git:*)"]
Validates query options using NimbleOptions.
Examples
iex> ClaudeCode.Options.validate_query_options([timeout: 60_000])
{:ok, [timeout: 60_000]}
iex> ClaudeCode.Options.validate_query_options([invalid: "option"])
{:error, %NimbleOptions.ValidationError{}}
Validates session options using NimbleOptions.
Examples
iex> ClaudeCode.Options.validate_session_options([api_key: "sk-test"])
{:ok, [api_key: "sk-test", timeout: 300_000]}
iex> ClaudeCode.Options.validate_session_options([])
{:error, %NimbleOptions.ValidationError{}}