Query command -- the primary interface for executing prompts.
Wraps claude -p <prompt> with the full set of CLI flags.
Usage
config = ClaudeWrapper.Config.new(working_dir: "/path/to/project")
# Build a query
query = ClaudeWrapper.Query.new("Fix the failing test")
|> ClaudeWrapper.Query.model("sonnet")
|> ClaudeWrapper.Query.max_turns(5)
|> ClaudeWrapper.Query.permission_mode(:bypass_permissions)
# Execute (one-shot, returns full result)
{:ok, result} = ClaudeWrapper.Query.execute(query, config)
# Or stream events
ClaudeWrapper.Query.stream(query, config)
|> Stream.each(&IO.inspect/1)
|> Stream.run()Summary
Functions
Add a directory for tool access.
Set agent name.
Provide custom agents as JSON.
Add an allowed tool.
Append to the system prompt.
Apply a keyword list of options to a query, calling the equivalent
Query setter for each known key. Unknown keys are silently ignored.
Set beta feature headers.
Enable brief mode.
Continue the most recent session.
Bypass all permission checks. Use in isolated worktrees.
Set debug log file.
Set debug filter.
Add a disallowed tool.
Set effort level.
Execute the query synchronously, returning a parsed %Result{}.
Set a fallback model.
Add a file resource.
Fork to a new session.
Include partial messages in streaming output.
Set input format.
Set JSON schema for structured output.
Set maximum budget in USD.
Set maximum turns.
Add an MCP config file path.
Set the model (e.g. "sonnet", "opus", "haiku").
Create a new query with the given prompt.
Disable session persistence.
Set output format.
Set permission mode.
Add a plugin directory.
Resume a specific session by ID.
Use a specific session ID.
Set settings source list.
Set settings JSON.
Execute the query and return a lazy stream of %StreamEvent{}.
Only use servers from --mcp-config.
Set the system prompt (overrides default).
Create tmux session.
Build the shell command string (for debugging).
Add a tool.
Create a git worktree for execution.
Types
@type effort() :: :low | :medium | :high | :max
@type input_format() :: :text | :stream_json
@type output_format() :: :text | :json | :stream_json
@type permission_mode() ::
:default | :accept_edits | :bypass_permissions | :dont_ask | :plan | :auto
@type t() :: %ClaudeWrapper.Query{ add_dir: [String.t()], agent: String.t() | nil, agents_json: String.t() | nil, allowed_tools: [String.t()], append_system_prompt: String.t() | nil, betas: String.t() | nil, brief: boolean(), continue_session: boolean(), dangerously_skip_permissions: boolean(), debug_file: String.t() | nil, debug_filter: String.t() | nil, disallowed_tools: [String.t()], effort: effort() | nil, fallback_model: String.t() | nil, files: [String.t()], fork_session: boolean(), include_partial_messages: boolean(), input_format: input_format() | nil, json_schema: String.t() | nil, max_budget_usd: float() | nil, max_turns: pos_integer() | nil, mcp_config: [String.t()], model: String.t() | nil, no_session_persistence: boolean(), output_format: output_format() | nil, permission_mode: permission_mode() | nil, plugin_dirs: [String.t()], prompt: String.t(), resume: String.t() | nil, session_id: String.t() | nil, setting_sources: String.t() | nil, settings: String.t() | nil, strict_mcp_config: boolean(), system_prompt: String.t() | nil, tmux: boolean(), tools: [String.t()], worktree: boolean() }
Functions
Add a directory for tool access.
Set agent name.
Provide custom agents as JSON.
Add an allowed tool.
Append to the system prompt.
Apply a keyword list of options to a query, calling the equivalent
Query setter for each known key. Unknown keys are silently ignored.
This is the shared mapping used by ClaudeWrapper.query/2,
ClaudeWrapper.stream/2, and ClaudeWrapper.Session.send/3. It
exists so the opt-to-setter mapping lives in one place rather than
being duplicated across each surface.
Boolean opts (e.g. :worktree, :dangerously_skip_permissions)
are applied when the value is true and ignored when false. List
opts (e.g. :allowed_tools, :add_dir) reduce over their list,
applying the per-item setter for each entry.
Examples
iex> q = ClaudeWrapper.Query.new("hi")
iex> q = ClaudeWrapper.Query.apply_opts(q, model: "sonnet", max_turns: 3, worktree: true)
iex> q.model
"sonnet"
iex> q.max_turns
3
iex> q.worktree
trueSet beta feature headers.
Enable brief mode.
Continue the most recent session.
Bypass all permission checks. Use in isolated worktrees.
Set debug log file.
Set debug filter.
Add a disallowed tool.
Set effort level.
@spec execute(t(), ClaudeWrapper.Config.t()) :: {:ok, ClaudeWrapper.Result.t()} | {:error, term()}
Execute the query synchronously, returning a parsed %Result{}.
Automatically sets --output-format json for parsing.
Set a fallback model.
Add a file resource.
Fork to a new session.
Include partial messages in streaming output.
@spec input_format(t(), input_format()) :: t()
Set input format.
Set JSON schema for structured output.
Set maximum budget in USD.
@spec max_turns(t(), pos_integer()) :: t()
Set maximum turns.
Add an MCP config file path.
Set the model (e.g. "sonnet", "opus", "haiku").
Create a new query with the given prompt.
Disable session persistence.
@spec output_format(t(), output_format()) :: t()
Set output format.
@spec permission_mode(t(), permission_mode()) :: t()
Set permission mode.
Add a plugin directory.
Resume a specific session by ID.
Use a specific session ID.
Set settings source list.
Set settings JSON.
@spec stream(t(), ClaudeWrapper.Config.t()) :: Enumerable.t()
Execute the query and return a lazy stream of %StreamEvent{}.
Uses a Port with :line mode to read NDJSON output line-by-line.
The port is opened when the stream is consumed and closed when
the stream terminates.
Only use servers from --mcp-config.
Set the system prompt (overrides default).
Create tmux session.
@spec to_command_string(t(), ClaudeWrapper.Config.t()) :: String.t()
Build the shell command string (for debugging).
Add a tool.
Create a git worktree for execution.