Documentation
¶
Overview ¶
Package client implements the interactive Client for multi-turn conversations with Claude.
The client package provides a stateful, bidirectional interface to the Claude CLI that maintains session state across multiple exchanges. Unlike the one-shot Query() function, Client enables:
- Multi-turn conversations with persistent context
- Interruption of Claude's processing
- Dynamic configuration changes (model, permissions)
- Hook system integration for tool permission management
The Client uses the protocol package for bidirectional control message handling and manages its own goroutines for message reading and routing.
Index ¶
- type Client
- func (c *Client) Close() error
- func (c *Client) GetMCPStatus(ctx context.Context) (*mcp.Status, error)
- func (c *Client) GetServerInfo() map[string]any
- func (c *Client) Interrupt(ctx context.Context) error
- func (c *Client) ListModels(_ context.Context) ([]models.Info, error)
- func (c *Client) Query(ctx context.Context, content message.UserMessageContent, sessionID ...string) error
- func (c *Client) ReceiveMessages(ctx context.Context) iter.Seq2[message.Message, error]
- func (c *Client) ReceiveResponse(ctx context.Context) iter.Seq2[message.Message, error]
- func (c *Client) ReconnectMCPServer(ctx context.Context, serverName string) error
- func (c *Client) RewindFiles(ctx context.Context, userMessageID string) error
- func (c *Client) SendToolResult(ctx context.Context, toolUseID, content string, isError bool) error
- func (c *Client) SetModel(ctx context.Context, model *string) error
- func (c *Client) SetPermissionMode(ctx context.Context, mode string) error
- func (c *Client) Start(ctx context.Context, options *config.Options) error
- func (c *Client) StartWithContent(ctx context.Context, content message.UserMessageContent, ...) error
- func (c *Client) StartWithStream(ctx context.Context, messages iter.Seq[message.StreamingMessage], ...) error
- func (c *Client) StopTask(ctx context.Context, taskID string) error
- func (c *Client) ToggleMCPServer(ctx context.Context, serverName string, enabled bool) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements the interactive client interface.
func New ¶
func New() *Client
New creates a new interactive client.
The client is not connected after creation. Call Start() with options to connect.
func (*Client) Close ¶
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) GetMCPStatus ¶
GetMCPStatus queries the CLI for live MCP server connection status. Returns the status of all configured MCP servers.
func (*Client) GetServerInfo ¶
GetServerInfo returns server initialization info including available commands. Returns nil if not connected or not in streaming mode.
func (*Client) Interrupt ¶
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
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 ¶
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 ¶
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
ReconnectMCPServer reconnects a disconnected or failed MCP server.
func (*Client) RewindFiles ¶
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) SendToolResult ¶
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) SetModel ¶
SetModel changes the AI model during conversation.
Pass nil to use the default model.
func (*Client) SetPermissionMode ¶
SetPermissionMode changes the permission mode during conversation. Valid modes: "default", "acceptEdits", "plan", "bypassPermissions".
func (*Client) Start ¶
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.
Source Files