ClaudeCode.Options (ClaudeCode v0.36.3)

Session option validation, CLI flag conversion, and configuration guide.

This module is the single source of truth for all options passed to ClaudeCode.start_link/1 or ClaudeCode.query/2. It provides validation using NimbleOptions, converts Elixir options to CLI flags, and manages option precedence.

Option Precedence

Options are resolved in this order (highest to lowest priority):

Session-level options — passed to start_link/1 or query/2
Application config — set in config/config.exs
Default values — built-in defaults
# Application config (lowest priority) config :claude_code, timeout: 300_000
# Session-level overrides app config {:ok, session} = ClaudeCode.start_link(timeout: 120_000)

Session Options

Options for ClaudeCode.start_link/1 and ClaudeCode.query/2. These are set once when the CLI subprocess is launched and apply to the entire session.

Authentication & Identity

Option	Type	Default	Description
`api_key`	string	`ANTHROPIC_API_KEY` env	Anthropic API key (passed via env var to CLI, never in arguments)
`name`	atom	-	Register the session process with a name for easy reference. See Named Sessions
`session_id`	string	auto-generated	Use a specific UUID instead of auto-generating one

Model & Prompting

Option	Type	Default	Description
`model`	string	"sonnet"	Model alias (`"sonnet"`, `"opus"`, `"haiku"`) or full model ID
`fallback_model`	string	-	Automatic fallback model when the primary is overloaded
`system_prompt`	string	-	Replace the entire default system prompt. See Modifying System Prompts
`append_system_prompt`	string	-	Append custom text to the end of the default system prompt. See Modifying System Prompts
`agent`	string	-	Select a named agent for the session. Must be defined in `:agents` or settings. See Subagents
`agents`	list/map	-	Define custom subagents. See Subagents and `ClaudeCode.Agent`
`thinking`	atom/tuple	-	Extended thinking: `:adaptive`, `:disabled`, or `{:enabled, budget_tokens: N}`
`effort`	atom	-	Thinking effort: `:low`, `:medium`, `:high`, `:max` (`:max` is Opus only)
`betas`	list	-	Beta feature flags (e.g. `["context-1m-2025-08-07"]`, API key users only)
`max_thinking_tokens`	integer	-	Deprecated: use `:thinking` instead

Limits

Option	Type	Default	Description
`timeout`	timeout	`:infinity`	Max wait for next message on the stream (ms or `:infinity`). Resets on each message
`control_timeout`	pos_integer	60_000	Max wait for CLI control responses (initialize handshake, MCP server startup)
`max_turns`	integer	unlimited	Maximum agentic turns (tool-use round trips). Exits with error when reached. See Cost Controls
`max_budget_usd`	number	-	Maximum dollar amount to spend on API calls before stopping. See Cost Controls
`max_buffer_size`	pos_integer	1_048_576	Max buffer size in bytes for incoming JSON data. Protects against unbounded memory growth

Tool Control

Option	Type	Default	Description
`tools`	atom/list	-	Restrict which built-in tools are available: `:default` (all), `[]` (none), or list of names. See Permissions
`allowed_tools`	list	-	Tools to auto-approve without prompting (e.g. `["View", "Bash(git:*)"]`). Unlisted tools fall through to `:permission_mode`. See Allow and deny rules
`disallowed_tools`	list	-	Tools to always deny. Checked first, overrides `:allowed_tools` and `:permission_mode`. See Allow and deny rules
`add_dir`	list	-	Additional directories Claude can access (each path validated as existing directory)
`tool_config`	map	-	Per-tool config (e.g. `%{"askUserQuestion" => %{"previewFormat" => "html"}}`)

Permissions & Security

Option	Type	Default	Description
`permission_mode`	atom	`:default`	`:default`, `:accept_edits`, `:bypass_permissions`, `:delegate`, `:dont_ask`, `:plan`. See Permission modes
`can_use_tool`	module/fn	-	Programmatic permission callback. Mutually exclusive with `:permission_prompt_tool`. See can_use_tool
`permission_prompt_tool`	string	-	MCP tool name for permission prompts in non-interactive mode. See Permission delegation
`sandbox`	struct/kw/map	-	Sandbox settings for bash command isolation. See `ClaudeCode.Sandbox` and Secure Deployment
`allow_dangerously_skip_permissions`	boolean	false	Enable permission bypassing as an option. Required when using `:bypass_permissions` mode
`dangerously_skip_permissions`	boolean	false	Directly bypass all permission checks. Only for sandboxes with no internet access

MCP Servers

See the MCP guide for setup, transport types, tool search, and authentication.

Option	Type	Default	Description
`mcp_config`	string	-	Path to MCP servers JSON config file (or JSON string). See From a config file
`mcp_servers`	map	-	Inline MCP server config. Values: Anubis module atom or config map per server. See In code
`strict_mcp_config`	boolean	false	Only use servers from `:mcp_config`/`:mcp_servers`, ignore global config. See Strict MCP configuration

Session Lifecycle

See the Sessions guide for resume, fork, and supervision patterns.

Option	Type	Default	Description
`resume`	string	-	Resume a previous conversation by session ID. See Resume by ID
`resume_session_at`	string	-	When resuming, only include messages up to this UUID (use with `:resume`)
`fork_session`	boolean	false	When resuming, create a new session ID instead of reusing the original. See Fork to explore alternatives
`continue`	boolean	false	Continue the most recent conversation in the current directory
`from_pr`	string/integer	-	Resume a session linked to a GitHub PR by number or URL
`no_session_persistence`	boolean	false	Disable session persistence — sessions won't be saved to disk or resumable
`worktree`	boolean/string	-	Run in an isolated git worktree (`true` for auto-named, or branch name string)

Output & Streaming

Option	Type	Default	Description
`output_format`	map	-	Structured output: `%{type: :json_schema, schema: schema_map}`. See Structured Outputs
`include_partial_messages`	boolean	false	Include partial message chunks for character-level streaming. See Streaming Output
`replay_user_messages`	boolean	false	Re-emit user messages from stdin back on stdout for acknowledgment
`prompt_suggestions`	boolean	false	Emit predicted next user prompts after each turn

Settings & Plugins

Option	Type	Default	Description
`settings`	map/string	-	Load additional settings from a file path, JSON string, or map (auto-encoded to JSON)
`setting_sources`	list	-	Which filesystem settings to load: `["user", "project", "local"]`. Include `"project"` for CLAUDE.md files
`plugins`	list	-	Load custom plugins (strings or maps with `type: :local`). See Plugins and `ClaudeCode.Plugin`
`hooks`	map	-	Lifecycle hook configurations for intercepting events. See Hooks
`disable_slash_commands`	boolean	false	Disable all skills and slash commands for this session. See Skills

Environment & CLI

Option	Type	Default	Description
`env`	map	`%{}`	Extra env vars merged into CLI subprocess. String values set, `false` unsets
`inherit_env`	atom/list	`:all`	System env inheritance: `:all`, `[]`, or list of names/`{:prefix, "..."}` tuples. See Environment Variable Control
`cwd`	string	-	Working directory for the CLI subprocess
`cli_path`	atom/string	`:bundled`	CLI binary resolution: `:bundled` (auto-install), `:global` (system), or explicit path
`file`	list	-	File resources to download at startup (`"file_id:relative_path"` format)
`enable_file_checkpointing`	boolean	false	Track file changes for rewinding. See File Checkpointing
`extra_args`	map	`%{}`	Additional CLI arguments passed directly to the binary (flag → value or `true` for boolean flags)

Debugging

Option	Type	Default	Description
`debug`	boolean/string	-	Enable debug mode with optional category filter (e.g. `"api,hooks"` or `"!1p,!file"`)
`debug_file`	string	-	Write debug logs to a specific file path (implicitly enables debug)

Elixir SDK Only

These options are specific to the Elixir SDK and have no CLI or upstream SDK equivalent.

Option	Type	Default	Description
`adapter`	tuple	CLI adapter	Backend adapter as `{Module, config}`. See `ClaudeCode.Adapter`, Distributed Sessions

Note: :name, :timeout, :control_timeout, :max_buffer_size, :inherit_env, and :hooks are also Elixir-only — they control SDK-side behavior and are not sent to the CLI. They appear in their respective sections above.

Application Configuration

Set defaults in config/config.exs:

config :claude_code,
  api_key: System.get_env("ANTHROPIC_API_KEY"),
  model: "sonnet",
  timeout: 180_000,
  system_prompt: "You are a helpful assistant",
  allowed_tools: ["View"]

CLI Binary Configuration

The SDK manages the Claude CLI binary via application config:

config :claude_code,
  cli_path: :bundled,               # :bundled (default), :global, or "/path/to/claude"
  cli_version: "x.y.z",            # Version to install (default: SDK's tested version)
  cli_dir: nil                      # Directory for downloaded binary (default: priv/bin/)

Mode	Value	Behavior
Bundled	`:bundled` (default)	Uses priv/bin/ binary. Auto-installs if missing. Verifies version matches SDK
Global	`:global`	Finds existing system install via PATH or common locations. No auto-install
Explicit	`"/path/to/claude"`	Uses that exact binary. Error if not found

Mix tasks: mix claude_code.install, mix claude_code.uninstall, mix claude_code.path.

For releases, see Hosting.

Environment-Specific Configuration

# config/dev.exs
config :claude_code,
  timeout: 60_000,
  permission_mode: :accept_edits

# config/prod.exs
config :claude_code,
  timeout: :infinity,
  permission_mode: :default

# config/test.exs
config :claude_code,
  api_key: "test-key",
  timeout: 5_000

Environment Variable Merging

Merge precedence (lowest to highest): system env (filtered by :inherit_env) → :env option → SDK-required vars → :api_key.

See Secure Deployment for production lockdown patterns.

Validation Errors

Invalid options raise descriptive errors:

{:ok, session} = ClaudeCode.start_link(timeout: "not a number")
# => ** (NimbleOptions.ValidationError) invalid value for :timeout option:
#       expected positive integer, got: "not a number"

Summary

Functions

apply_app_config_defaults(session_opts)

Applies application config defaults to session options.

get_app_config()

Gets application configuration for claude_code.

session_schema()

Returns the session options schema.

validate_session_options(opts)

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.

session_schema()

Returns the session options schema.

validate_session_options(opts)

Validates session options using NimbleOptions.

The CLI will handle API key resolution from the environment if not provided.

Examples

iex> ClaudeCode.Options.validate_session_options([api_key: "sk-test"])
{:ok, [api_key: "sk-test", timeout: :infinity]}

iex> ClaudeCode.Options.validate_session_options([])
{:ok, [timeout: :infinity]}