client

func (*Client) ApplyFlagSettings ¶ added in v0.0.7

func (c *Client) ApplyFlagSettings(ctx context.Context, settings map[string]any) error

ApplyFlagSettings merges the provided settings into the flag settings layer.

func (*Client) CancelAsyncMessage ¶ added in v0.0.7

func (c *Client) CancelAsyncMessage(
	ctx context.Context,
	messageUUID string,
) (*protocol.CancelAsyncMessageResult, error)

CancelAsyncMessage cancels a queued async message by UUID.

func (*Client) Close ¶

func (c *Client) Close() error

Close terminates the session and cleans up resources.

After Close(), the client cannot be reused - create a new client with New(). This method is safe to call multiple times.

func (*Client) GetContextUsage ¶ added in v0.0.7

func (c *Client) GetContextUsage(ctx context.Context) (*protocol.ContextUsage, error)

GetContextUsage queries the CLI for the current context usage breakdown.

func (*Client) GetMCPStatus ¶

func (c *Client) GetMCPStatus(ctx context.Context) (*mcp.Status, error)

GetMCPStatus queries the CLI for live MCP server connection status. Returns the status of all configured MCP servers.

func (*Client) GetServerInfo ¶

func (c *Client) GetServerInfo() (*protocol.ServerInfo, error)

GetServerInfo returns typed server initialization info including available commands. Returns ErrClientNotConnected when no session is active.

func (*Client) GetSettings ¶ added in v0.0.7

func (c *Client) GetSettings(ctx context.Context) (*protocol.SettingsSnapshot, error)

GetSettings returns the effective merged settings and per-source raw settings.

func (*Client) GetTransportHealth ¶ added in v0.0.7

func (c *Client) GetTransportHealth() TransportHealth

GetTransportHealth returns the current observed transport health snapshot.

func (*Client) Interrupt ¶

func (c *Client) Interrupt(ctx context.Context) error

Interrupt sends an interrupt signal to stop Claude's current processing.

This uses the protocol controller to send a control_request with subtype "interrupt".

func (*Client) ListModels ¶ added in v0.0.2

func (c *Client) ListModels(_ context.Context) ([]models.Info, error)

ListModels returns the SDK's static Claude model catalog in the ListModels payload shape.

func (*Client) Query ¶

func (c *Client) Query(ctx context.Context, content message.UserMessageContent, sessionID ...string) error

Query sends user content to Claude.

This method sends a user_message to the CLI and returns immediately. Use Receive() to get the responses. Optional sessionID defaults to "default" for multi-session support.

func (*Client) ReceiveMessages ¶

func (c *Client) ReceiveMessages(ctx context.Context) iter.Seq2[message.Message, error]

ReceiveMessages returns an iterator that yields messages indefinitely. Messages are yielded as they arrive until EOF, an error occurs, or context is cancelled. Unlike ReceiveResponse, this iterator does not stop at ResultMessage.

func (*Client) ReceiveResponse ¶

func (c *Client) ReceiveResponse(ctx context.Context) iter.Seq2[message.Message, error]

ReceiveResponse returns an iterator that yields messages until a ResultMessage is received. Messages are yielded as they arrive for streaming consumption. The iterator stops after yielding the ResultMessage.

func (*Client) ReconnectMCPServer ¶ added in v0.0.2

func (c *Client) ReconnectMCPServer(ctx context.Context, serverName string) error

ReconnectMCPServer reconnects a disconnected or failed MCP server.

func (*Client) ReloadPlugins ¶ added in v0.0.7

func (c *Client) ReloadPlugins(ctx context.Context) (*protocol.ReloadPluginsResult, error)

ReloadPlugins reloads plugins from disk and returns refreshed session metadata.

func (*Client) RewindFiles ¶

func (c *Client) RewindFiles(ctx context.Context, userMessageID string) (*protocol.RewindFilesResult, error)

RewindFiles rewinds tracked files to their state at a specific user message.

The userMessageID should be the ID of a previous user message in the conversation. The CLI must support file checkpointing for this to work.

func (*Client) SeedReadState ¶ added in v0.0.7

func (c *Client) SeedReadState(ctx context.Context, path string, mtime int64) error

SeedReadState seeds the CLI read-state cache for Edit validation.

func (*Client) SendToolResult ¶

func (c *Client) SendToolResult(ctx context.Context, toolUseID, content string, isError bool) error

SendToolResult sends a tool_result message back to Claude for a pending tool_use. This allows the SDK to intercept tool calls (e.g. AskUserQuestion), gather a result externally, and feed it back so Claude continues processing.

func (*Client) SetMCPServers ¶ added in v0.0.7

func (c *Client) SetMCPServers(
	ctx context.Context,
	servers map[string]mcp.ServerConfig,
) (*protocol.MCPSetServersResult, error)

SetMCPServers replaces the dynamically managed MCP server set.

func (*Client) SetMaxThinkingTokens ¶ added in v0.0.7

func (c *Client) SetMaxThinkingTokens(ctx context.Context, maxTokens *int) error

SetMaxThinkingTokens changes the max thinking token budget during conversation.

func (*Client) SetModel ¶

func (c *Client) SetModel(ctx context.Context, model *string) error

SetModel changes the AI model during conversation.

Pass nil to use the default model.

func (*Client) SetPermissionMode ¶

func (c *Client) SetPermissionMode(ctx context.Context, mode string) error

SetPermissionMode changes the permission mode during conversation. Valid modes: "default", "acceptEdits", "plan", "dontAsk", "bypassPermissions".

func (*Client) Start ¶

func (c *Client) Start(ctx context.Context, options *config.Options) error

Start establishes a connection to the Claude CLI.

This method spawns the CLI subprocess and sets up bidirectional communication. For interactive sessions, no initial prompt is sent - use Query() to send prompts.

Returns CLINotFoundError if the CLI binary cannot be located, or CLIConnectionError if the process fails to start.

func (*Client) StartWithContent ¶ added in v0.0.5

func (c *Client) StartWithContent(
	ctx context.Context,
	content message.UserMessageContent,
	options *config.Options,
) error

StartWithContent establishes a connection and immediately sends initial user content.

This is a convenience method equivalent to calling Start() followed by Query(). The content is sent to the "default" session.

func (*Client) StartWithStream ¶

func (c *Client) StartWithStream(
	ctx context.Context,
	messages iter.Seq[message.StreamingMessage],
	options *config.Options,
) error

StartWithStream establishes a connection and streams initial messages.

This method starts the client in streaming mode and consumes messages from the provided iterator. Messages are sent to the CLI via stdin. The iterator runs in a separate goroutine; use context cancellation to abort message streaming. EndInput is called automatically when the iterator completes.

func (*Client) StopTask ¶ added in v0.0.2

func (c *Client) StopTask(ctx context.Context, taskID string) error

StopTask stops a running task by task ID.

func (*Client) ToggleMCPServer ¶ added in v0.0.2

func (c *Client) ToggleMCPServer(ctx context.Context, serverName string, enabled bool) error

ToggleMCPServer enables or disables an MCP server.

func (*Client) UpdateEnvironmentVariables ¶ added in v0.0.7

func (c *Client) UpdateEnvironmentVariables(ctx context.Context, variables map[string]string) error

UpdateEnvironmentVariables updates environment variables for the running session.