# `ClaudeWrapper.Query`
[🔗](https://github.com/joshrotenberg/claude_wrapper_ex/blob/main/lib/claude_wrapper/query.ex#L1)

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

# `effort`

```elixir
@type effort() :: :low | :medium | :high | :max
```

# `input_format`

```elixir
@type input_format() :: :text | :stream_json
```

# `output_format`

```elixir
@type output_format() :: :text | :json | :stream_json
```

# `permission_mode`

```elixir
@type permission_mode() ::
  :default | :accept_edits | :bypass_permissions | :dont_ask | :plan | :auto
```

# `t`

```elixir
@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()
}
```

# `add_dir`

```elixir
@spec add_dir(t(), String.t()) :: t()
```

Add a directory for tool access.

# `agent`

```elixir
@spec agent(t(), String.t()) :: t()
```

Set agent name.

# `agents_json`

```elixir
@spec agents_json(t(), String.t()) :: t()
```

Provide custom agents as JSON.

# `allowed_tool`

```elixir
@spec allowed_tool(t(), String.t()) :: t()
```

Add an allowed tool.

# `append_system_prompt`

```elixir
@spec append_system_prompt(t(), String.t()) :: t()
```

Append to the system prompt.

# `betas`

```elixir
@spec betas(t(), String.t()) :: t()
```

Set beta feature headers.

# `brief`

```elixir
@spec brief(t()) :: t()
```

Enable brief mode.

# `continue_session`

```elixir
@spec continue_session(t()) :: t()
```

Continue the most recent session.

# `dangerously_skip_permissions`

```elixir
@spec dangerously_skip_permissions(t()) :: t()
```

Bypass all permission checks. Use in isolated worktrees.

# `debug_file`

```elixir
@spec debug_file(t(), String.t()) :: t()
```

Set debug log file.

# `debug_filter`

```elixir
@spec debug_filter(t(), String.t()) :: t()
```

Set debug filter.

# `disallowed_tool`

```elixir
@spec disallowed_tool(t(), String.t()) :: t()
```

Add a disallowed tool.

# `effort`

```elixir
@spec effort(t(), effort()) :: t()
```

Set effort level.

# `execute`

```elixir
@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.

# `fallback_model`

```elixir
@spec fallback_model(t(), String.t()) :: t()
```

Set a fallback model.

# `file`

```elixir
@spec file(t(), String.t()) :: t()
```

Add a file resource.

# `fork_session`

```elixir
@spec fork_session(t()) :: t()
```

Fork to a new session.

# `include_partial_messages`

```elixir
@spec include_partial_messages(t()) :: t()
```

Include partial messages in streaming output.

# `input_format`

```elixir
@spec input_format(t(), input_format()) :: t()
```

Set input format.

# `json_schema`

```elixir
@spec json_schema(t(), String.t()) :: t()
```

Set JSON schema for structured output.

# `max_budget_usd`

```elixir
@spec max_budget_usd(t(), float()) :: t()
```

Set maximum budget in USD.

# `max_turns`

```elixir
@spec max_turns(t(), pos_integer()) :: t()
```

Set maximum turns.

# `mcp_config`

```elixir
@spec mcp_config(t(), String.t()) :: t()
```

Add an MCP config file path.

# `model`

```elixir
@spec model(t(), String.t()) :: t()
```

Set the model (e.g. "sonnet", "opus", "haiku").

# `new`

```elixir
@spec new(String.t()) :: t()
```

Create a new query with the given prompt.

# `no_session_persistence`

```elixir
@spec no_session_persistence(t()) :: t()
```

Disable session persistence.

# `output_format`

```elixir
@spec output_format(t(), output_format()) :: t()
```

Set output format.

# `permission_mode`

```elixir
@spec permission_mode(t(), permission_mode()) :: t()
```

Set permission mode.

# `plugin_dir`

```elixir
@spec plugin_dir(t(), String.t()) :: t()
```

Add a plugin directory.

# `resume`

```elixir
@spec resume(t(), String.t()) :: t()
```

Resume a specific session by ID.

# `session_id`

```elixir
@spec session_id(t(), String.t()) :: t()
```

Use a specific session ID.

# `setting_sources`

```elixir
@spec setting_sources(t(), String.t()) :: t()
```

Set settings source list.

# `settings`

```elixir
@spec settings(t(), String.t()) :: t()
```

Set settings JSON.

# `stream`

```elixir
@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.

# `strict_mcp_config`

```elixir
@spec strict_mcp_config(t()) :: t()
```

Only use servers from --mcp-config.

# `system_prompt`

```elixir
@spec system_prompt(t(), String.t()) :: t()
```

Set the system prompt (overrides default).

# `tmux`

```elixir
@spec tmux(t()) :: t()
```

Create tmux session.

# `to_command_string`

```elixir
@spec to_command_string(t(), ClaudeWrapper.Config.t()) :: String.t()
```

Build the shell command string (for debugging).

# `tool`

```elixir
@spec tool(t(), String.t()) :: t()
```

Add a tool.

# `worktree`

```elixir
@spec worktree(t()) :: t()
```

Create a git worktree for execution.

---

*Consult [api-reference.md](api-reference.md) for complete listing*