ClaudeWrapper (ClaudeWrapper v0.4.0)

Copy Markdown View Source

Elixir wrapper for the Claude Code CLI.

Provides a typed interface for executing queries against the claude CLI, with support for one-shot execution and streaming NDJSON output.

Quick start

# One-shot query (convenience — uses default config)
{:ok, result} = ClaudeWrapper.query("Explain this error: ...")

# With options
{:ok, result} = ClaudeWrapper.query("Fix the bug in lib/foo.ex",
  model: "sonnet",
  working_dir: "/path/to/project",
  max_turns: 5,
  permission_mode: :bypass_permissions
)

# Streaming
ClaudeWrapper.stream("Implement the feature described in issue #42",
  working_dir: "/path/to/project"
)
|> Stream.each(fn event -> IO.inspect(event.type) end)
|> Stream.run()

# Full control via Query builder
config = ClaudeWrapper.Config.new(working_dir: "/path/to/project")

ClaudeWrapper.Query.new("Fix the tests")
|> ClaudeWrapper.Query.model("sonnet")
|> ClaudeWrapper.Query.dangerously_skip_permissions()
|> ClaudeWrapper.Query.max_turns(10)
|> ClaudeWrapper.Query.execute(config)

Commands

Binary discovery

The claude binary is found via (in order):

  1. :binary option passed directly
  2. CLAUDE_CLI environment variable
  3. System PATH lookup

Summary

Functions

agents(opts \\ [])

List configured agents.

auth_status(opts \\ [])

Check authentication status.

doctor(opts \\ [])

Run claude doctor.

query(prompt, opts \\ [])

Execute a one-shot query and return the result.

raw(args, opts \\ [])

Run an arbitrary CLI command that isn't wrapped by a dedicated module.

stream(prompt, opts \\ [])

Execute a query and return a lazy stream of %StreamEvent{} structs.

version(opts \\ [])

Get the CLI version.

Functions

agents(opts \\ [])

@spec agents(keyword()) :: {:ok, [map()]} | {:error, term()}

List configured agents.

Returns a list of agent maps with :name and :model keys.

Options

  • :setting_sources - comma-separated setting sources (e.g. "user,project")

auth_status(opts \\ [])

@spec auth_status(keyword()) :: {:ok, map()} | {:error, term()}

Check authentication status.

doctor(opts \\ [])

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

Run claude doctor.

query(prompt, opts \\ [])

@spec query(
  String.t(),
  keyword()
) :: {:ok, ClaudeWrapper.Result.t()} | {:error, term()}

Execute a one-shot query and return the result.

Convenience wrapper that builds a Config and Query from keyword options. Returns {:ok, %Result{}} on success or {:error, reason} on failure.

Options

Config options (passed to ClaudeWrapper.Config.new/1):

  • :binary - Path to claude binary
  • :working_dir - Working directory
  • :env - Environment variables
  • :timeout - Timeout in ms
  • :verbose - Enable verbose output
  • :debug - Enable debug output

Query options (passed to Query builder):

  • :model - Model name
  • :system_prompt - System prompt override
  • :max_turns - Max turns
  • :max_budget_usd - Budget limit
  • :permission_mode - Permission mode atom
  • :dangerously_skip_permissions - Bypass permissions (boolean)
  • :session_id - Session ID
  • :continue_session - Continue recent session (boolean)
  • :resume - Resume session ID

raw(args, opts \\ [])

@spec raw(
  [String.t()],
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Run an arbitrary CLI command that isn't wrapped by a dedicated module.

This is the escape hatch for new or experimental CLI subcommands.

Examples

ClaudeWrapper.raw(["config", "list"])
ClaudeWrapper.raw(["plugin", "install", "my-plugin"], working_dir: "/tmp")

stream(prompt, opts \\ [])

@spec stream(
  String.t(),
  keyword()
) :: Enumerable.t()

Execute a query and return a lazy stream of %StreamEvent{} structs.

The subprocess starts when the stream is consumed. Accepts the same options as query/2.

version(opts \\ [])

@spec version(keyword()) :: {:ok, map()} | {:error, term()}

Get the CLI version.