ClaudeCode (ClaudeCode v0.1.0)

View Source

Elixir SDK for Claude Code CLI.

This module provides the main interface for interacting with Claude Code through the command-line interface. It manages sessions as GenServer processes that communicate with the Claude CLI via JSON streaming over stdout.

Example

{:ok, session} = ClaudeCode.start_link(api_key: "sk-ant-...")
{:ok, response} = ClaudeCode.query_sync(session, "Hello, Claude!")
IO.puts(response.content)

Summary

Functions

Checks if a session is alive.

Clears the current session ID to start a fresh conversation.

Gets the current session ID for conversation continuity.

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

Sends a query to Claude asynchronously and returns a request ID.

Sends a synchronous query to Claude and waits for the complete response.

Starts a new Claude Code session.

Stops a Claude Code session.

Types

message_stream()

@type message_stream() :: Enumerable.t(ClaudeCode.Message.t())

query_response()

@type query_response() :: {:ok, String.t()} | {:error, term()}

session()

@type session() :: pid() | atom() | {:via, module(), any()}

Functions

alive?(session)

@spec alive?(session()) :: boolean()

Checks if a session is alive.

Examples

true = ClaudeCode.alive?(session)

clear(session)

@spec clear(session()) :: :ok

Clears the current session ID to start a fresh conversation.

This will cause the next query to start a new conversation context rather than continuing the existing one. Useful when you want to reset the conversation history.

Examples

:ok = ClaudeCode.clear(session)

# Next query will start fresh
{:ok, response} = ClaudeCode.query_sync(session, "Hello!")

get_session_id(session)

@spec get_session_id(session()) :: {:ok, String.t() | nil}

Gets the current session ID for conversation continuity.

Returns the session ID that Claude CLI is using to maintain conversation context. This ID is automatically captured from CLI responses and used for subsequent queries to continue the conversation.

Examples

{:ok, session_id} = ClaudeCode.get_session_id(session)
# => {:ok, "abc123-session-id"}

# For a new session with no queries yet
{:ok, nil} = ClaudeCode.get_session_id(session)

query(session, prompt, opts \\ [])

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

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

This function returns immediately with a stream that emits messages as they arrive from Claude. The stream will automatically complete when Claude finishes responding.

Options

Query-level options override session-level options. See ClaudeCode.Options.query_schema/0 for all available query options.

Examples

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

# Stream with option overrides
session
|> ClaudeCode.query("Explain quantum computing",
     system_prompt: "Focus on practical applications",
     allowed_tools: ["View"])
|> ClaudeCode.Stream.text_content()
|> Enum.each(&IO.write/1)

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

query_async(session, prompt, opts \\ [])

@spec query_async(session(), String.t(), keyword()) ::
  {:ok, reference()} | {:error, term()}

Sends a query to Claude asynchronously and returns a request ID.

This function returns immediately with a request reference that can be used to track the query. Messages will be sent to the calling process as they arrive.

Examples

{:ok, request_ref} = ClaudeCode.query_async(session, "Complex task")

# Receive messages for this request
receive do
  {:claude_message, ^request_ref, message} ->
    IO.inspect(message)
end

query_sync(session, prompt, opts \\ [])

@spec query_sync(session(), String.t(), keyword()) :: query_response()

Sends a synchronous query to Claude and waits for the complete response.

This function blocks until Claude has finished responding. For streaming responses, use query/3 instead.

Options

Query-level options override session-level options. See ClaudeCode.Options.query_schema/0 for all available query options.

Examples

{:ok, response} = ClaudeCode.query_sync(session, "What is 2 + 2?")
IO.puts(response)
# => "4"

# With option overrides
{:ok, response} = ClaudeCode.query_sync(session, "Complex query",
  system_prompt: "Focus on performance optimization",
  allowed_tools: ["View"],
  timeout: 120_000
)

start_link(opts)

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

Starts a new Claude Code session.

Options

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

Examples

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

# 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: 180_000,
  name: :my_session
)

stop(session)

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

Stops a Claude Code session.

Examples

:ok = ClaudeCode.stop(session)