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.
Minimal mode: skip hooks, LSP, plugins, and settings (--bare).
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.
Disable all slash commands / skills (--disable-slash-commands).
Add a disallowed tool.
Set effort level.
Exclude dynamic system-prompt sections (--exclude-dynamic-system-prompt-sections).
Execute the query synchronously, returning a parsed %Result{}.
Set a fallback model.
Add a file resource.
Fork to a new session.
Resume a session linked to a PR (--from-pr <number|url>).
Seal the ambient ~/.claude config so a programmatic run's surface is
exactly what was provided explicitly.
Include hook lifecycle events in the output stream (--include-hook-events).
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").
Set a display name for the session (--name).
Create a new query with the given prompt.
Disable session persistence.
Set output format.
Set permission mode.
Add a plugin directory.
Fetch a plugin .zip from a URL (--plugin-url). Repeatable.
Enable prompt suggestions (--prompt-suggestions).
Re-emit user messages from stdin (--replay-user-messages). Mainly for stream/duplex use.
Resume a specific session by ID.
Start with all customizations disabled (--safe-mode).
Use a specific session ID.
Set settings source list.
Set settings JSON.
The spawn-time flag subset of a query, for a long-lived
ClaudeWrapper.DuplexSession.
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 (--worktree). See worktree/2 for a named worktree.
Create a named git worktree for execution (--worktree <name>).
Types
@type effort() :: :low | :medium | :high | :xhigh | :max
@type hermetic() :: :full | :project
@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, bare: boolean(), betas: String.t() | nil, brief: boolean(), continue_session: boolean(), dangerously_skip_permissions: boolean(), debug_file: String.t() | nil, debug_filter: String.t() | nil, disable_slash_commands: boolean(), disallowed_tools: [String.t()], effort: effort() | nil, exclude_dynamic_system_prompt_sections: boolean(), fallback_model: String.t() | nil, files: [String.t()], fork_session: boolean(), from_pr: String.t() | nil, hermetic: hermetic() | nil, include_hook_events: 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, name: String.t() | nil, no_session_persistence: boolean(), output_format: output_format() | nil, permission_mode: permission_mode() | nil, plugin_dirs: [String.t()], plugin_urls: [String.t()], prompt: String.t(), prompt_suggestions: boolean(), replay_user_messages: boolean(), resume: String.t() | nil, safe_mode: boolean(), 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() | String.t() }
Functions
Add a directory for tool access.
Set agent name.
Provide custom agents as JSON.
@spec allowed_tool(t(), String.t() | ClaudeWrapper.ToolPattern.t()) :: t()
Add an allowed tool.
Accepts either a plain CLI-format string ("Bash(git log:*)") or a
ClaudeWrapper.ToolPattern.t/0, which is rendered to its string
form. The stored field stays a list of strings.
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
trueMinimal mode: skip hooks, LSP, plugins, and settings (--bare).
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.
Disable all slash commands / skills (--disable-slash-commands).
@spec disallowed_tool(t(), String.t() | ClaudeWrapper.ToolPattern.t()) :: t()
Add a disallowed tool.
Accepts either a plain CLI-format string or a
ClaudeWrapper.ToolPattern.t/0, mirroring allowed_tool/2.
Set effort level.
Exclude dynamic system-prompt sections (--exclude-dynamic-system-prompt-sections).
@spec execute(t(), ClaudeWrapper.Config.t()) :: {:ok, ClaudeWrapper.Result.t()} | {:error, ClaudeWrapper.Error.t()}
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.
Resume a session linked to a PR (--from-pr <number|url>).
Analogous to resume/2 but keyed on a pull request rather than a
session id. The value is a PR number or URL.
Seal the ambient ~/.claude config so a programmatic run's surface is
exactly what was provided explicitly.
A preset over three flags, expanded at flag-build time (never here), so
the seal is order-independent and an explicit setting_sources/2 always
wins over the scope's default:
--setting-sources(the ambient-config seal)--strict-mcp-config(only servers from--mcp-config)--exclude-dynamic-system-prompt-sections(reproducibility)
The scope sets the seal level:
:full->--setting-sources ""-- drops user + project + local ambient config; only claude's built-in agents remain.:project->--setting-sources user-- seals project + local ambient config, keeps the user's global~/.claude.
Hermetic seals the promptspace WITHOUT changing auth: it never emits
--bare (which would force ANTHROPIC_API_KEY billing). OAuth /
keychain / subscription auth is untouched.
Include hook lifecycle events in the output stream (--include-hook-events).
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").
Set a display name for the session (--name).
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.
Fetch a plugin .zip from a URL (--plugin-url). Repeatable.
Enable prompt suggestions (--prompt-suggestions).
Re-emit user messages from stdin (--replay-user-messages). Mainly for stream/duplex use.
Resume a specific session by ID.
Start with all customizations disabled (--safe-mode).
Use a specific session ID.
Set settings source list.
Set settings JSON.
The spawn-time flag subset of a query, for a long-lived
ClaudeWrapper.DuplexSession.
Reuses build_args/1 (the single source of flag emission, so the
duplex and one-shot paths cannot drift), then removes the flags a
duplex session owns itself: the transport formats
(--output-format / --input-format / --include-partial-messages,
which the session fixes to its stream-json protocol) and the leading
--print <prompt> pair (in duplex the prompt is a per-turn
stream-json message, not an argv). Everything else -- model, system
prompt, permission mode, tool allow/deny lists, mcp config, effort,
turn/budget caps, session continuity, and so on -- is spawn-safe and
passes through.
@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 (--worktree). See worktree/2 for a named worktree.
Create a named git worktree for execution (--worktree <name>).