ClaudeCode.Options (ClaudeCode v0.1.0)

View Source

Handles 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):

  1. Query-level options
  2. Session-level options
  3. Application configuration
  4. 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

apply_app_config_defaults(session_opts)

Applies application config defaults to session options.

Session options take precedence over app config.

get_app_config()

Gets application configuration for claude_code.

Returns only valid option keys from the session schema.

merge_options(session_opts, query_opts)

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]

query_schema()

Returns the query options schema.

resolve_final_options(session_opts, query_opts)

Resolves final options using complete precedence chain.

Precedence: query > session > app config > defaults

session_schema()

Returns the session options schema.

to_cli_args(opts)

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:*)"]

validate_query_options(opts)

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{}}

validate_session_options(opts)

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{}}