🤖 Claude Code SDK for Elixir

The most ergonomic way to integrate Claude AI into your Elixir applications.

Hex.pmDocumentationLicenseElixir

ClaudeCode

🎯 30-Second Demo

# Start a session and query Claude (uses ANTHROPIC_API_KEY from env)

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



# Real-time streaming responses

session

|> ClaudeCode.query_stream("Explain Elixir GenServers")

|> ClaudeCode.Stream.text_content()

|> Enum.each(&IO.write/1)  # Watch Claude type in real-time! 🎬



# Conversation continuity - Claude remembers context

ClaudeCode.query(session, "My favorite language is Elixir")

ClaudeCode.query(session, "What's my favorite language?")

# => "Your favorite language is Elixir!"

📦 Installation

Step 1: Add to your mix.exs

def deps do

  [{:claude_code, "~> 0.5.0"}]

end

Step 2: Install dependencies

mix deps.get

Step 3: Get the Claude CLI

# Install from claude.ai/code

claude --version  # Verify installation

Step 4: Set your API key

# The SDK uses ANTHROPIC_API_KEY from your environment

export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"



# Or configure in config/config.exs (optional)

config :claude_code, api_key: System.get_env("ANTHROPIC_API_KEY")

🎉 Ready to go! Try the quick demo above.

⚡ Quick Examples

# Basic usage (uses ANTHROPIC_API_KEY from environment)

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

{:ok, response} = ClaudeCode.query(session, "Hello, Claude!")



# File operations

ClaudeCode.query(session, "Review my mix.exs file",

  allowed_tools: ["View", "Edit"])



# 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)

ClaudeCode.query(:assistant, "Help with this task")

📖 Complete Getting Started Guide →

🚀 Key Features

🏭 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

{:ok, review} = ClaudeCode.query(:code_reviewer, "Review this code")

Benefits:

Phoenix Integration

# Use in LiveViews and Controllers

def handle_event("ask_claude", %{"message" => message}, socket) do

  case ClaudeCode.query(:assistant, message) do

    {:ok, response} -> {:noreply, assign(socket, response: response)}

    {:error, _} -> {:noreply, put_flash(socket, :error, "Claude unavailable")}

  end

end

Error Handling

case ClaudeCode.query(session, "Hello") do

  {:ok, response} -> IO.puts(response)

  {:error, :timeout} -> IO.puts("Request timed out")

  {:error, {:cli_not_found, msg}} -> IO.puts("CLI error: #{msg}")

  {:error, {:claude_error, msg}} -> IO.puts("Claude error: #{msg}")

end

Multi-turn Conversations

Sessions automatically maintain context across queries:

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



# First turn

{:ok, response1} = ClaudeCode.query(session, "What's the capital of France?")

IO.puts(response1)  # Paris



# Second turn - context is preserved automatically

{:ok, response2} = ClaudeCode.query(session, "What about Germany?")

IO.puts(response2)  # Berlin



# Get session ID for later resume

{:ok, 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)

{:ok, response3} = ClaudeCode.query(new_session, "What was the first capital I asked about?")

IO.puts(response3)  # Paris

Benefits:

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!

📚 Documentation

🤝 Contributing

We ❤️ contributions! Whether it's:

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 on top of the Claude Code CLI and designed for the Elixir community.

Made with ❤️ for Elixir developers who want the best AI integration experience.