Struct Query 

pub struct Query { /* private fields */ }

Low-level query session handler for Claude Code CLI communication.

Manages the bidirectional JSON stream protocol between the SDK and the CLI. On startup, a background tokio task is spawned to continuously read messages from the transport and route them:

• Control responses are delivered to the waiting control-request caller via oneshot channels.
• Control requests (permissions, hooks, MCP) are handled by the background task.
• SDK messages (user, assistant, system, result) are parsed and delivered via an mpsc channel.

This architecture mirrors the Python SDK’s task-group model and enables concurrent send and receive operations.

Implementations

impl Query

pub async fn initialize( &mut self, hooks_config: Map<String, Value>, ) -> Result<Option<Value>>

Sends the initialization handshake to the CLI.

Registers hook callbacks and agent definitions with the CLI process, and waits for the initialization response.

Returns the initialization response payload, or None if not in streaming mode.

Example

use claude_code::Query;
use serde_json::Map;
use serde_json::Value;

let _ = query.initialize(Map::<String, Value>::new()).await?;

pub fn initialization_result(&self) -> Option<Value>

Returns the initialization result from the CLI handshake.

Returns None if initialize() has not been called yet.

Example

use claude_code::Query;

fn demo(query: &Query) {
    let _info = query.initialization_result();
}

pub async fn send_user_message( &self, prompt: &str, session_id: &str, ) -> Result<()>

Sends a user text message to the CLI.

Example

use claude_code::Query;

query.send_user_message("hello", "default").await?;

pub async fn send_raw_message(&self, message: Value) -> Result<()>

Sends a raw JSON message to the CLI without any transformation.

Example

use claude_code::Query;
use serde_json::json;

query.send_raw_message(json!({"type":"user","message":{"role":"user","content":"hi"}})).await?;

pub async fn send_input_messages(&self, messages: Vec<Value>) -> Result<()>

Sends multiple input messages to the CLI without closing stdin.

Example

use claude_code::Query;
use serde_json::json;

query
    .send_input_messages(vec![json!({"type":"user","message":{"role":"user","content":"hello"}})])
    .await?;

pub async fn send_input_from_stream<S>(&self, messages: S) -> Result<()>

where S: Stream<Item = Value> + Unpin,

Sends streamed input messages to the CLI without closing stdin.

Example

use claude_code::Query;
use futures::stream;
use serde_json::json;

query
    .send_input_from_stream(stream::iter(vec![json!({"type":"user","message":{"role":"user","content":"hello"}})]))
    .await?;

pub fn spawn_input_from_stream<S>( &self, messages: S, ) -> Result<JoinHandle<Result<()>>>

where S: Stream<Item = Value> + Send + Unpin + 'static,

Spawns a background task that streams input messages to the CLI.

This is useful for long-lived or unbounded input streams where the caller should continue processing messages concurrently.

The returned task completes when the input stream ends or a write error occurs. It does not close stdin.

Example

use claude_code::Query;
use futures::stream;
use serde_json::json;

let handle = query.spawn_input_from_stream(stream::iter(vec![
    json!({"type":"user","message":{"role":"user","content":"hello"}}),
]))?;
handle.await??;

pub async fn stream_input(&self, messages: Vec<Value>) -> Result<()>

Streams multiple messages to the CLI and closes the input stream.

If SDK MCP servers or hooks are present, stdin close is deferred until the first result message is received (or a timeout expires).

Example

use claude_code::Query;
use serde_json::json;

query
    .stream_input(vec![json!({"type":"user","message":{"role":"user","content":"hello"}})])
    .await?;

pub async fn stream_input_from_stream<S>(&self, messages: S) -> Result<()>

where S: Stream<Item = Value> + Unpin,

Streams messages from an async stream source and closes the input stream.

Example

use claude_code::Query;
use futures::stream;
use serde_json::json;

query
    .stream_input_from_stream(stream::iter(vec![json!({"type":"user","message":{"role":"user","content":"hello"}})]))
    .await?;

pub async fn end_input(&self) -> Result<()>

Closes the input stream without sending any messages.

Example

use claude_code::Query;

query.end_input().await?;

pub async fn receive_next_message(&mut self) -> Result<Option<Message>>

Receives the next content message from the CLI.

Messages are delivered by the background reader task via an mpsc channel. Control messages are handled transparently by the background task.

Returns None when the stream is exhausted (no more messages).

Example

use claude_code::Query;

while let Some(message) = query.receive_next_message().await? {
    println!("{message:?}");
}

pub async fn get_mcp_status(&self) -> Result<McpStatusResponse>

Queries the status of connected MCP servers via the CLI.

Example

use claude_code::Query;

let _status = query.get_mcp_status().await?;

pub async fn interrupt(&self) -> Result<()>

Sends an interrupt signal to the CLI to stop the current operation.

Example

use claude_code::Query;

query.interrupt().await?;

pub async fn set_permission_mode(&self, mode: &str) -> Result<()>

Changes the permission mode via a control request.

Example

use claude_code::Query;

query.set_permission_mode("plan").await?;

pub async fn set_model(&self, model: Option<&str>) -> Result<()>

Changes the model used by the CLI via a control request.

Example

use claude_code::Query;

query.set_model(Some("sonnet")).await?;

pub async fn rewind_files(&self, user_message_id: &str) -> Result<()>

Rewinds file changes to a specific user message checkpoint.

Example

use claude_code::Query;

query.rewind_files("user-msg-1").await?;

pub async fn reconnect_mcp_server(&self, server_name: &str) -> Result<()>

Reconnects a disconnected or failed MCP server.

pub async fn toggle_mcp_server( &self, server_name: &str, enabled: bool, ) -> Result<()>

Enables or disables an MCP server.

pub async fn stop_task(&self, task_id: &str) -> Result<()>

Stops a running task.

pub async fn close(self) -> Result<()>

Closes the query session.

Example

use claude_code::Query;

query.close().await?;

Trait Implementations

impl Drop for Query

fn drop(&mut self)

Executes the destructor for this type.