Configuration Internals

This guide documents the SDK's centralized configuration system. Every tunable constant — timeouts, buffer sizes, environment variable names, CLI flags — lives in a single Config.* module namespace and can be overridden at runtime via Application.put_env/3 or at compile time via config/config.exs.

Architecture

ClaudeAgentSDK.Config              (top-level facade, mock mode, CLI stream module)
  ├── Config.Timeouts              (all timeout values)
  ├── Config.Buffers               (buffer sizes, truncation lengths)
  ├── Config.Auth                  (auth file paths, TTLs, token prefixes)
  ├── Config.CLI                   (CLI versions, flags, executable discovery)
  ├── Config.Env                   (environment variable name registry)
  └── Config.Orchestration         (concurrency limits, retries, backoff)

Each sub-module follows the same pattern:

1. A private get/2 helper reads from Application.get_env(:claude_agent_sdk, __MODULE__, [])
2. Public zero-arity functions return the value for a named key
3. Every function has a built-in default that matches the original hardcoded value

This means no behaviour changes out of the box — the defaults are identical to the values that were previously scattered as @module_attributes and inline literals.

Quick Reference

Config.Timeouts

All values in milliseconds unless noted.

Config.Buffers

Config.Auth

Config.CLI

Config.Env

Every function returns a string literal — the canonical environment variable name.

Config.Orchestration

Overriding at Runtime

Via config.exs

# config/config.exs
config :claude_agent_sdk, ClaudeAgentSDK.Config.Timeouts,
  client_init_ms: 90_000,
  query_total_ms: 5_400_000

config :claude_agent_sdk, ClaudeAgentSDK.Config.Buffers,
  max_stdout_buffer_bytes: 2_097_152

config :claude_agent_sdk, ClaudeAgentSDK.Config.Auth,
  token_store_path: "~/.my_app/token.json",
  session_max_age_days: 60

config :claude_agent_sdk, ClaudeAgentSDK.Config.CLI,
  minimum_version: "2.1.0",
  recommended_version: "2.1.74"

config :claude_agent_sdk, ClaudeAgentSDK.Config.Orchestration,
  max_concurrent: 10,
  max_retries: 5

Via Application.put_env at Runtime

# Useful for tests or dynamic configuration
Application.put_env(
  :claude_agent_sdk,
  ClaudeAgentSDK.Config.Timeouts,
  query_total_ms: 10_000
)

# In tests, always restore original values:
setup do
  original = Application.get_env(:claude_agent_sdk, Timeouts)
  on_exit(fn ->
    if original, do: Application.put_env(:claude_agent_sdk, Timeouts, original),
    else: Application.delete_env(:claude_agent_sdk, Timeouts)
  end)
end

Per-Environment Overrides

# config/test.exs
config :claude_agent_sdk, ClaudeAgentSDK.Config.Timeouts,
  client_init_ms: 5_000,       # faster for tests
  query_total_ms: 10_000

# config/prod.exs
config :claude_agent_sdk, ClaudeAgentSDK.Config.Timeouts,
  query_total_ms: 7_200_000    # 2 hours for production

Design Decisions

Why Not a Single Flat Config Module?

Grouping by domain (timeouts, buffers, auth, etc.) provides:

• Discoverability: Config.Timeouts. tab-completion shows all timeouts
• Selective override: configure only the domain you care about
• Documentation: each module's @moduledoc is a focused reference

Why Runtime Functions Instead of Module Attributes?

Module attributes (@timeout 60_000) are evaluated at compile time. Functions like Timeouts.client_init_ms() are evaluated at runtime, which means:

• Changes via Application.put_env take effect immediately
• No recompilation needed to adjust values
• Tests can override values per-test without affecting other tests

The performance cost is negligible (~1 µs per Application.get_env call, which is ETS-backed).

Why Keep Struct Defaults as Literals?

Elixir defstruct requires compile-time default values. Where a struct field previously used @some_attribute, we replace it with the same literal value. The struct default is just an initial value — the init/1 callback (or factory function) overwrites it from Config at runtime.

Adding New Configuration Values

1. Choose the appropriate sub-module (or create a new one under Config/)
2. Add a public function with @doc, @spec, and a sensible default
3. Add a test in test/claude_agent_sdk/config/
4. Use the function in your module instead of a hardcoded value
5. Update this guide's quick reference table