ClaudeCode (ClaudeCode v0.1.0)
View SourceElixir 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
Functions
Checks if a session is alive.
Examples
true = ClaudeCode.alive?(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!")
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)
@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()
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
@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
)
@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
)
@spec stop(session()) :: :ok
Stops a Claude Code session.
Examples
:ok = ClaudeCode.stop(session)