ClaudeWrapper.Config (ClaudeWrapper v0.14.0)

Shared client configuration for the Claude CLI.

Equivalent to the Rust Claude struct -- holds binary path, working directory, environment variables, and default options that apply across all commands.

Usage

config = ClaudeWrapper.Config.new()
config = ClaudeWrapper.Config.new(working_dir: "/path/to/project")

Summary

Functions

base_args(config)

Build the base command args from config (global flags).

cmd_opts(config)

Build the cmd options (working dir, env) for System.cmd/Port.

exec(config, args)

Run a claude subcommand, bounded by config.timeout.

find_binary()

Find the claude binary path.

new(opts \\ [])

Create a new config from keyword options.

Types

t()

@type t() :: %ClaudeWrapper.Config{
  binary: String.t(),
  debug: boolean(),
  env: [{String.t(), String.t()}],
  timeout: pos_integer() | nil,
  verbose: boolean(),
  working_dir: String.t() | nil
}

Functions

base_args(config)

@spec base_args(t()) :: [String.t()]

Build the base command args from config (global flags).

cmd_opts(config)

@spec cmd_opts(t()) :: keyword()

Build the cmd options (working dir, env) for System.cmd/Port.

exec(config, args)

@spec exec(t(), [String.t()]) :: {String.t(), non_neg_integer()}

Run a claude subcommand, bounded by config.timeout.

System.cmd/3 has no timeout, so the CLI subcommand wrappers used it directly and a wedged subcommand blocked the calling process forever, silently discarding the configured :timeout. This runs the command in a Task and bounds it with Task.yield/2 + Task.shutdown/1 (mirroring the one-shot Runner.Port path), returning System.cmd/3's {output, exit_code} on completion. On timeout it kills the task and synthesizes {message, 124} (124 is the conventional timeout exit code), so a caller's existing {_, code} clause surfaces it as a command_failed instead of hanging. A nil timeout (the default) is unbounded, exactly as before. A spawn failure (missing binary) still crashes the caller via the task link, as the direct call did.

find_binary()

@spec find_binary() :: String.t()

Find the claude binary path.

Checks in order:

CLAUDE_CLI environment variable
System PATH

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new config from keyword options.

Options

:binary - Path to the claude binary (default: auto-discover via CLAUDE_CLI/PATH). Pass the atom :bundled to resolve the opt-in bundled binary (ClaudeWrapper.Bundled.path/0); install it first with mix claude_wrapper.install.
:working_dir - Working directory for the subprocess
:env - List of {key, value} environment variable tuples
:timeout - Command timeout in milliseconds (default nil: unbounded). Applies to query/2, Command.run/3, raw/2, and the CLI subcommand wrappers (via exec/2). Streaming (ClaudeWrapper.stream/2) is bounded only by its per-frame idle deadline, not this whole-run value.
:verbose - Enable verbose output
:debug - Enable debug output