claude

Documentation

Index

• func MapModelName(backendModel string) string
• func ValidateEnvironment() error
• type ClaudeAgent
• type Client
  • func NewClient(claudePath string) *Client
  • func (c *Client) Generate(ctx context.Context, userMessage string, opts GenerateOpts) (*Response, error)
  • func (c *Client) GenerateStreaming(ctx context.Context, userMessage string, opts GenerateOpts, ...) (*Response, error)
  • func (c *Client) RunInteractive(ctx context.Context, prompt string, opts InteractiveOpts, ...) (*Response, error)
  • func (c *Client) StartInteractiveStreaming(ctx context.Context, userMessage string, opts GenerateOpts, ...) (*InteractiveSession, error)
  • func (c *Client) WithModel(model string) *Client
• type GenerateOpts
• type InteractiveOpts
• type InteractiveSession
  • func (s *InteractiveSession) CloseInput()
  • func (s *InteractiveSession) SendUserMessage(message string) error
  • func (s *InteractiveSession) Stderr() string
  • func (s *InteractiveSession) Wait() (*Response, error)
• type Response
• type StreamEvent
• type Usage

Functions

func MapModelName

func MapModelName(backendModel string) string

MapModelName preserves the configured model identifier.

func ValidateEnvironment

func ValidateEnvironment() error

ValidateEnvironment checks that Claude Code CLI is installed and authenticated.

Types

type ClaudeAgent

type ClaudeAgent interface {
	// Generate runs a one-shot prompt and returns the response.
	Generate(ctx context.Context, userMessage string, opts GenerateOpts) (*Response, error)

	// GenerateStreaming runs a prompt with real-time event streaming.
	GenerateStreaming(ctx context.Context, userMessage string, opts GenerateOpts, onEvent func(StreamEvent)) (*Response, error)

	// RunInteractive runs an interactive session with HITL support.
	// Claude streams events via onEvent. When Claude asks a question,
	// onQuestion is called with the question text; it must return the
	// user's response (blocking). The session continues until Claude
	// finishes without asking a question.
	RunInteractive(ctx context.Context, prompt string, opts InteractiveOpts, onEvent func(StreamEvent), onQuestion func(question string) string) (*Response, error)
}

ClaudeAgent abstracts Claude Code interactions for pipeline phases.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps the Claude Code CLI for LLM calls.

func NewClient

func NewClient(claudePath string) *Client

NewClient creates a new Claude Code client.

func (*Client) Generate

func (c *Client) Generate(ctx context.Context, userMessage string, opts GenerateOpts) (*Response, error)

Generate sends a prompt to Claude Code and returns the response.

func (*Client) GenerateStreaming

func (c *Client) GenerateStreaming(ctx context.Context, userMessage string, opts GenerateOpts, onEvent func(StreamEvent)) (*Response, error)

GenerateStreaming sends a prompt and streams events via callback. The callback is called for each meaningful event (tool calls, results). Returns the final Response when complete.

func (*Client) RunInteractive

func (c *Client) RunInteractive(ctx context.Context, prompt string, opts InteractiveOpts, onEvent func(StreamEvent), onQuestion func(question string) string) (*Response, error)

RunInteractive runs an interactive Claude Code session with human-in-the-loop support. It uses StartInteractiveStreaming (bidirectional stream-json) and a state machine to detect when Claude is asking a question vs autonomously using tools.

When Claude emits assistant text followed by no tool_use_start (detected via result event or idle timeout), onQuestion is called with the question text. The caller must return the user's response, which is sent back to Claude.

The session continues until Claude finishes a turn without asking a question (i.e., emits a result event after tool use, or the process exits).

func (*Client) StartInteractiveStreaming

func (c *Client) StartInteractiveStreaming(ctx context.Context, userMessage string, opts GenerateOpts, onEvent func(StreamEvent)) (*InteractiveSession, error)

StartInteractiveStreaming creates an interactive Claude Code session with bidirectional stream-json communication. Unlike GenerateStreaming (which sends the prompt and closes stdin), this keeps stdin open so follow-up user messages can be sent via SendUserMessage().

The onEvent callback is called for each stream event. When Claude emits an assistant message and goes idle (waiting for user input), the caller should detect this, collect user input, and call session.SendUserMessage().

When done, call session.CloseInput() then session.Wait() to get the result.

func (*Client) WithModel

func (c *Client) WithModel(model string) *Client

WithModel returns a copy of the client with a specific model.

type GenerateOpts

type GenerateOpts struct {
	SystemPrompt       string
	AppendSystemPrompt string   // --append-system-prompt (added to auto-discovered CLAUDE.md)
	JSONSchema         string   // JSON schema for structured output
	MaxTurns           int      // Max agentic turns (default 1)
	AllowedTools       []string // MCP tools to allow
	MCPConfig          string   // Path to MCP config file
	Model              string   // Model override for this call
	WorkDir            string   // Working directory for the claude process
	SessionID          string   // Resume a previous session
	Images             []string // Absolute paths to image files to include in the prompt
}

GenerateOpts holds options for a Generate call.

type InteractiveOpts

type InteractiveOpts struct {
	GenerateOpts
}

InteractiveOpts extends GenerateOpts with interactive session settings.

type InteractiveSession

type InteractiveSession struct {
	// contains filtered or unexported fields
}

InteractiveSession represents a running Claude Code subprocess with bidirectional stream-json communication. It allows sending follow-up user messages while streaming events — enabling human-in-the-loop interactions where Claude asks questions and the caller provides answers.

func (*InteractiveSession) CloseInput

func (s *InteractiveSession) CloseInput()

CloseInput signals that no more user messages will be sent. Claude Code will finish processing and return a result.

func (*InteractiveSession) SendUserMessage

func (s *InteractiveSession) SendUserMessage(message string) error

SendUserMessage sends a follow-up user message to the running Claude session. Use this when Claude emits an assistant message asking a question and is waiting for user input.

func (*InteractiveSession) Stderr

func (s *InteractiveSession) Stderr() string

Stderr returns any stderr output captured from the Claude Code process.

func (*InteractiveSession) Wait

func (s *InteractiveSession) Wait() (*Response, error)

Wait blocks until the session completes and returns the final response.

type Response

type Response struct {
	Result       string          `json:"result"`
	RawJSON      json.RawMessage `json:"-"`
	TotalCostUSD float64         `json:"total_cost_usd"`
	SessionID    string          `json:"session_id"`
	NumTurns     int             `json:"num_turns"`
	Usage        Usage           `json:"usage"`
}

Response represents the parsed response from Claude Code.

type StreamEvent

type StreamEvent struct {
	Type    string // "assistant", "tool_use", "tool_use_start", "tool_input_delta", "tool_result", "result", "system", "content_block_delta"
	Subtype string // e.g. "init"

	// For tool_use events
	ToolName  string
	ToolInput json.RawMessage

	// For assistant text events and content_block_delta events
	Text string

	// For result events
	Result    string
	SessionID string
	CostUSD   float64
	NumTurns  int
	IsError   bool
	Usage     Usage
}

StreamEvent represents a parsed event from Claude Code's stream-json output.

type Usage

type Usage struct {
	InputTokens              int `json:"input_tokens"`
	OutputTokens             int `json:"output_tokens"`
	CacheCreationInputTokens int `json:"cache_creation_input_tokens"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens"`
}

Usage holds token usage data from a Claude response.