Elixir wrapper for the Claude Code CLI.

Two ways to drive claude from Elixir:

1. ClaudeWrapper.DuplexSession -- a GenServer that holds one claude subprocess open for the lifetime of a conversation. Streams partial tokens as they arrive, supports clean mid-turn cancellation, and routes tool-permission prompts back to the host. The right fit for chat UIs, agent runtimes, Phoenix servers, and any long-running OTP host.
2. The convenience ClaudeWrapper.query/2 and ClaudeWrapper.stream/2 functions in this module -- one subprocess per turn, simple request/response. The right fit for mix tasks, escripts, batch jobs, and anything else that runs and exits.

Both modes are first-class. Pick whichever matches the lifecycle of the host using claude_wrapper.

Long-lived chat-style sessions (DuplexSession)

config = ClaudeWrapper.Config.new(working_dir: ".")
{:ok, pid} = ClaudeWrapper.DuplexSession.start_link(config: config)

ClaudeWrapper.DuplexSession.subscribe(pid)
{:ok, result} = ClaudeWrapper.DuplexSession.send(pid, "Explain this codebase.")

# Subscriber inbox now holds streaming events:
#   {:claude, {:assistant, msg}}
#   {:claude, {:stream_event, msg}}    -- partial token deltas
#   {:claude, {:result, %ClaudeWrapper.Result{}}}

ClaudeWrapper.DuplexSession.close(pid)

See ClaudeWrapper.DuplexSession for the permission callback, interrupt API, and full event vocabulary. ClaudeWrapper.DuplexIEx wraps it with REPL helpers that stream tokens to stdout live.

One-shot queries

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

Multi-turn continuity for one-shot mode (Session)

ClaudeWrapper.Session threads --resume <session_id> across one-shot calls so you can have a multi-turn conversation without holding a subprocess open. Use it when you want a struct-passing API rather than a process API, or when turns are far enough apart that cold-start cost doesn't matter.

Other modules

• ClaudeWrapper.Query -- the query builder
• ClaudeWrapper.SessionServer -- supervised wrapper for Session
• ClaudeWrapper.McpConfig -- programmatic .mcp.json builder
• ClaudeWrapper.Retry -- exponential backoff
• ClaudeWrapper.Telemetry -- :telemetry spans for exec/stream/session
• ClaudeWrapper.Commands.{Auth, Mcp, Plugin, Marketplace, Doctor, Version} -- CLI subcommand wrappers

Binary discovery

The claude binary is found via (in order):

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