Puck.Backends.ClaudeAgentSDK (Puck v0.2.9)

View Source

Backend implementation using the Claude Agent SDK.

This backend uses the Claude Code CLI (via the Elixir SDK) to run prompts. It supports your existing Claude subscription (Pro/Max) when authenticated via claude login.

Authentication

The backend uses your Claude subscription. Make sure you're logged in:

# In your terminal
claude login

If ANTHROPIC_API_KEY is set, it will use API credits instead.

Configuration

Backend options are passed in the client tuple:

  • :cwd - Working directory for file operations (defaults to current directory)
  • :allowed_tools - List of tools Claude can use (e.g., ["Read", "Glob", "Grep"])
  • :disallowed_tools - List of tools to disable
  • :permission_mode - Permission handling (:default, :accept_edits, :bypass_permissions)
  • :max_turns - Maximum conversation turns
  • :model - Model to use (e.g., "sonnet", "opus")
  • :output_format - Response format (:text, :json, or schema map)
  • :sandbox - Sandbox settings map with :enabled, :root, :allowed_paths, etc.

Examples

# Basic usage - read-only agent
client = Puck.Client.new(
  {Puck.Backends.ClaudeAgentSDK, %{
    allowed_tools: ["Read", "Glob", "Grep"],
    permission_mode: :bypass_permissions
  }}
)

{:ok, response, _ctx} = Puck.call(client, "What files are in this directory?")

# Code editing agent
client = Puck.Client.new(
  {Puck.Backends.ClaudeAgentSDK, %{
    allowed_tools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"],
    permission_mode: :accept_edits,
    cwd: "/path/to/project"
  }}
)

{:ok, response, _ctx} = Puck.call(client, "Fix the bug in auth.py")

Notes

  • The Claude Agent SDK is an agentic system - it may make multiple tool calls before returning a final result
  • For structured outputs, use the :output_schema option with a Zoi schema
  • Streaming returns intermediate messages as Claude works

See the claude_agent_sdk documentation for more details.