@spec cli_version() :: String.t()

Returns the configured CLI version.

This is the Claude Code CLI version the SDK is configured to use. It can be overridden via application config (:cli_version), otherwise defaults to the version the SDK was tested against.

Examples

iex> ClaudeCode.cli_version()
"2.1.76"

@spec query(
  String.t(),
  keyword()
) :: query_response()

Sends a one-off query to Claude and returns the result.

This is a convenience function that automatically manages a temporary session. For multi-turn conversations, use start_link/1 and stream/3 instead.

Options

See ClaudeCode.Options.session_schema/0 for all available options.

Examples

# Simple one-off query
{:ok, result} = ClaudeCode.query("What is 2 + 2?", api_key: "sk-ant-...")
IO.puts(result)  # Result implements String.Chars
# => "4"

# With options
{:ok, result} = ClaudeCode.query("Complex query",
  api_key: "sk-ant-...",
  model: "opus",
  system_prompt: "Focus on performance optimization"
)

# Handle errors
case ClaudeCode.query("Do something risky", api_key: "sk-ant-...") do
  {:ok, result} -> IO.puts(result.result)
  {:error, %ClaudeCode.Message.ResultMessage{is_error: true} = result} ->
    IO.puts("Claude error: #{result.result}")
  {:error, reason} -> IO.puts("Error: #{inspect(reason)}")
end

@spec start_link(keyword()) :: GenServer.on_start()

Starts a new Claude Code session.

The session automatically connects to a persistent CLI subprocess on startup. This enables efficient multi-turn conversations without CLI restart overhead.

Options

For complete option documentation including types, validation rules, and examples, see ClaudeCode.Options.session_schema/0 and the ClaudeCode.Options module.

Key options:

• :api_key - Anthropic API key (or set ANTHROPIC_API_KEY env var)
• :resume - Session ID to resume a previous conversation
• :model - Claude model to use
• :system_prompt - Custom system prompt

Examples

# Start a basic session
{:ok, session} = ClaudeCode.start_link(api_key: "sk-ant-...")

# Start with application config (if api_key is configured)
{:ok, session} = ClaudeCode.start_link()

# Resume a previous conversation
{:ok, session} = ClaudeCode.start_link(
  api_key: "sk-ant-...",
  resume: "previous-session-id"
)

# Start with custom 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: :infinity,
  name: :my_session
)

@spec stop(session()) :: :ok

Stops a Claude Code session.

This closes the CLI subprocess and cleans up resources.

Examples

:ok = ClaudeCode.stop(session)

@spec stream(session(), String.t(), keyword()) :: message_stream()

Sends a query to a session and returns a stream of messages.

This is the primary API for interacting with Claude. The stream emits messages as they arrive and automatically completes when Claude finishes responding.

Options

Stream-level options control local stream behavior only:

• :timeout — Max wait for next message (default: :infinity)
• :filter — Message type filter: :all, :assistant, :tool_use, :result (default: :all)

All other configuration is set at session creation via ClaudeCode.start_link/1 or ClaudeCode.query/2.

Examples

# Stream all messages
session
|> ClaudeCode.stream("Write a hello world program")
|> Enum.each(&IO.inspect/1)

# Stream with a timeout
session
|> ClaudeCode.stream("Explain quantum computing", timeout: 30_000)
|> ClaudeCode.Stream.text_content()
|> Enum.each(&IO.write/1)

# Collect all text content
text =
  session
  |> ClaudeCode.stream("Tell me a story")
  |> ClaudeCode.Stream.text_content()
  |> Enum.join()

# Multi-turn conversation
{:ok, session} = ClaudeCode.start_link(api_key: "sk-ant-...")

ClaudeCode.stream(session, "What is 5 + 3?")
|> Enum.each(&IO.inspect/1)

ClaudeCode.stream(session, "Multiply that by 2")
|> Enum.each(&IO.inspect/1)

@spec version() :: String.t()

Returns the SDK version string.

Examples

iex> ClaudeCode.version()
"0.36.3"