🤖 Claude Code SDK for Elixir

The Elixir SDK for building AI agents with Claude Code.

• 🔄 Native Streaming: Built on Elixir Streams for real-time responses
• 💬 Conversation Continuity: Automatic context retention across queries
• 🏭 Production-Ready Supervision: Fault-tolerant GenServers with automatic restarts
• ⚡ High-Performance Concurrency: Multiple concurrent sessions with Elixir's actor model
• 🔧 Zero-Config Phoenix: Drop-in support for LiveView and Phoenix apps
• 🧪 Built-in Test Stubs: Mock Claude responses for fast, deterministic tests without API calls
• 🔌 MCP Tool Integration: Expose Elixir functions to Claude via Hermes

🎯 30-Second Demo

# Simple one-off query (uses ANTHROPIC_API_KEY from env)
{:ok, result} = ClaudeCode.query("Explain Elixir GenServers in one sentence")
IO.puts(result.result)

# For multi-turn conversations, use sessions with streaming
{:ok, session} = ClaudeCode.start_link()

session
|> ClaudeCode.stream("My favorite language is Elixir")
|> Stream.run()

# Claude remembers context across queries
session
|> ClaudeCode.stream("What's my favorite language?")
|> ClaudeCode.Stream.text_content()
|> Enum.each(&IO.write/1)
# => "Your favorite language is Elixir!"

ClaudeCode.stop(session)

📦 Installation

Step 1: Add to your mix.exs

def deps do
  [{:claude_code, "~> 0.17"}]
end

Step 2: Install dependencies and CLI

mix deps.get
mix claude_code.install  # Downloads and installs the Claude CLI

Note: The CLI is installed to priv/bin/ by default. Alternatively, install it manually:

curl -fsSL https://claude.ai/install.sh | bash

Step 3: Authenticate (choose one)

# Option A: Use your Claude subscription (no API key needed)
claude  # Then type /login to authenticate

# Option B: Use an API key
export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"

🎉 Ready to go! Try the quick demo above.

⚡ Quick Examples

# Basic usage (uses ANTHROPIC_API_KEY from environment)
{:ok, session} = ClaudeCode.start_link()

# Stream response messages
session
|> ClaudeCode.stream("Hello, Claude!")
|> Enum.each(&IO.inspect/1)

# File operations
session
|> ClaudeCode.stream("Review my mix.exs file", allowed_tools: ["View", "Edit"])
|> ClaudeCode.Stream.final_text()

# Custom agents
agents = %{
  "code-reviewer" => %{
    "description" => "Expert code reviewer. Use proactively after code changes.",
    "prompt" => "You are a senior code reviewer. Focus on quality and best practices.",
    "tools" => ["Read", "Grep", "Glob"],
    "model" => "sonnet"
  }
}
{:ok, session} = ClaudeCode.start_link(agents: agents)

# Production with supervision
{:ok, _} = ClaudeCode.Supervisor.start_link(name: :assistant)
:assistant
|> ClaudeCode.stream("Help with this task")
|> ClaudeCode.Stream.final_text()

📖 Complete Getting Started Guide →

🏭 Production Usage

Supervised Sessions

# In your application.ex
def start(_type, _args) do
  children = [
    MyAppWeb.Endpoint,
    {ClaudeCode.Supervisor, [
      [name: :code_reviewer, system_prompt: "You review code"],
      [name: :general_assistant]
    ]}
  ]
  Supervisor.start_link(children, strategy: :one_for_one)
end

# Use from anywhere in your app
review =
  :code_reviewer
  |> ClaudeCode.stream("Review this code")
  |> ClaudeCode.Stream.final_text()

Benefits:

• ✅ Fault tolerance - Sessions restart automatically on crashes
• ✅ Zero downtime - Hot code reloading preserves session state
• ✅ Global access - Named sessions work from anywhere in your app
• ✅ Distributed support - Sessions work across Elixir clusters

Phoenix Integration

# Simple controller usage
def ask(conn, %{"prompt" => prompt}) do
  response =
    :assistant
    |> ClaudeCode.stream(prompt)
    |> ClaudeCode.Stream.final_text()

  json(conn, %{response: response})
end

For LiveView with real-time streaming, use stream/3 with a Task:

# LiveView with streaming responses
def handle_event("send", %{"message" => msg}, socket) do
  parent = self()
  Task.start(fn ->
    :assistant
    |> ClaudeCode.stream(msg, include_partial_messages: true)
    |> ClaudeCode.Stream.text_deltas()
    |> Enum.each(&send(parent, {:chunk, &1}))
    send(parent, :complete)
  end)
  {:noreply, assign(socket, streaming: true)}
end

def handle_info({:chunk, chunk}, socket) do
  {:noreply, assign(socket, response: socket.assigns.response <> chunk)}
end

def handle_info(:complete, socket) do
  {:noreply, assign(socket, streaming: false)}
end

📖 Full Phoenix Integration Guide →

Error Handling

# Stream errors are thrown and can be caught
try do
  session
  |> ClaudeCode.stream("Hello")
  |> Enum.to_list()
catch
  {:stream_timeout, _ref} -> IO.puts("Request timed out")
  {:stream_init_error, {:cli_not_found, msg}} -> IO.puts("CLI error: #{msg}")
  {:stream_error, reason} -> IO.puts("Stream error: #{inspect(reason)}")
end

# Or use one-off query with result pattern matching
case ClaudeCode.query("Hello") do
  {:ok, result} -> IO.puts(result.result)
  {:error, %{is_error: true, result: msg}} -> IO.puts("Error: #{msg}")
  {:error, reason} -> IO.puts("Error: #{inspect(reason)}")
end

Multi-turn Conversations

Sessions automatically maintain context across queries:

{:ok, session} = ClaudeCode.start_link()

# First turn
session
|> ClaudeCode.stream("What's the capital of France?")
|> ClaudeCode.Stream.text_content()
|> Enum.each(&IO.write/1)  # Paris

# Second turn - context is preserved automatically
session
|> ClaudeCode.stream("What about Germany?")
|> ClaudeCode.Stream.text_content()
|> Enum.each(&IO.write/1)  # Berlin

# Get session ID for later resume
session_id = ClaudeCode.get_session_id(session)

ClaudeCode.stop(session)

# Resume later with the same context
{:ok, new_session} = ClaudeCode.start_link(resume: session_id)

new_session
|> ClaudeCode.stream("What was the first capital I asked about?")
|> ClaudeCode.Stream.text_content()
|> Enum.each(&IO.write/1)  # Paris

Benefits:

• ✅ Persistent connection - Single CLI process handles all queries
• ✅ Auto-connect/disconnect - No manual lifecycle management
• ✅ Resume support - Continue previous conversations with resume: session_id
• ✅ Lower latency - No startup overhead between turns

Tool Callbacks

Monitor tool executions for logging, auditing, or analytics:

callback = fn event ->
  Logger.info("Tool #{event.name} executed",
    input: event.input,
    result: event.result,
    is_error: event.is_error
  )
end

{:ok, session} = ClaudeCode.start_link(tool_callback: callback)

MCP Integration (Optional)

Expose Elixir tools to Claude using Hermes MCP:

# Add {:hermes_mcp, "~> 0.14"} to your deps

# Start MCP server with your tools
{:ok, config_path} = ClaudeCode.MCP.Server.start_link(
  server: MyApp.MCPServer,
  port: 9001
)

# Connect ClaudeCode to MCP server
{:ok, session} = ClaudeCode.start_link(mcp_config: config_path)

# Claude can now use your custom tools!

🧪 Testing

ClaudeCode includes a test adapter for fast, deterministic tests without API calls:

test "handles greeting" do
  ClaudeCode.Test.stub(ClaudeCode, fn _query, _opts ->
    [ClaudeCode.Test.text("Hello! How can I help?")]
  end)

  {:ok, session} = ClaudeCode.start_link()
  result = session |> ClaudeCode.stream("Hi") |> ClaudeCode.Stream.final_text()
  assert result == "Hello! How can I help?"
end

Includes message helpers (text, tool_use, tool_result, thinking), dynamic stubs, and concurrent test support.

📖 Full Testing Guide →

📚 Documentation

• 🚀 Getting Started - Step-by-step tutorial for new users
• 📖 Documentation Hub - All guides and references
• 🏭 Production Guide - Fault-tolerant production deployments
• 💻 Examples - Real-world usage patterns and code samples
• 📖 API Reference - Complete API documentation
• 🔧 Troubleshooting - Common issues and solutions

🤝 Contributing

We ❤️ contributions! Whether it's:

• 🐛 Bug reports - Found an issue? Let us know!
• 💡 Feature requests - Have an idea? We'd love to hear it!
• 📝 Documentation - Help make our docs even better
• 🔧 Code contributions - PRs welcome!

See our Contributing Guide to get started.

🛠️ Development

# Clone and setup
git clone https://github.com/guess/claude_code.git
cd claude_code
mix deps.get

# Run tests and quality checks
mix test
mix quality  # format, credo, dialyzer

📜 License

MIT License - see LICENSE for details.

Built for Elixir developers on top of the Claude Code CLI.