claudecli

claudecli-go

Go package for invoking the Claude Code CLI as a subprocess with typed streaming events, functional options, and pluggable execution.

Requires: claude CLI installed and on PATH.

Install

go get github.com/allbin/claudecli-go

See CHANGELOG.md for what changed between versions and upgrade notes.

Quick start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/allbin/claudecli-go"
)

func main() {
    // One-off blocking call
    text, result, err := claudecli.RunText(context.Background(), "Say hello in 5 words")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(text)
    fmt.Printf("Cost: $%.4f, Tokens: %d (%d in / %d out)\n",
        result.CostUSD, result.Usage.TotalTokens(),
        result.Usage.InputTokens, result.Usage.OutputTokens)
}

Streaming

stream := claudecli.Run(ctx, "Explain quicksort",
    claudecli.WithModel(claudecli.ModelSonnet),
)

for event := range stream.Events() {
    switch e := event.(type) {
    case *claudecli.TextEvent:
        fmt.Print(e.Content)
    case *claudecli.ThinkingEvent:
        // model thinking output
    case *claudecli.ToolUseEvent:
        fmt.Printf("[tool: %s]\n", e.Name)
    case *claudecli.StderrEvent:
        log.Println("stderr:", e.Content)
    case *claudecli.ErrorEvent:
        log.Println("error:", e.Err)
    case *claudecli.ResultEvent:
        fmt.Printf("\n--- Done: $%.4f ---\n", e.CostUSD)
    }
}

Typed JSON responses

type Analysis struct {
    Summary string   `json:"summary"`
    Tags    []string `json:"tags"`
}

analysis, result, err := claudecli.RunJSON[Analysis](ctx, client, prompt,
    claudecli.WithModel(claudecli.ModelHaiku),
)

RunJSON automatically strips markdown code fences (```json ... ```) before unmarshaling.

Blocking mode

When you don't need streaming events, use RunBlocking for a simpler, more reliable path. Uses --output-format json internally.

result, err := client.RunBlocking(ctx, "Summarize this file")
fmt.Println(result.Text)
fmt.Printf("Cost: $%.4f, Turns: %d\n", result.CostUSD, result.NumTurns)

For typed JSON with schema validation:

type Analysis struct {
    Summary string   `json:"summary"`
    Tags    []string `json:"tags"`
}

// When WithJSONSchema is set, parses the schema-validated structured_output field.
// Otherwise, parses the text result with code fence stripping.
analysis, result, err := claudecli.RunBlockingJSON[Analysis](ctx, client, prompt,
    claudecli.WithJSONSchema(`{"type":"object","properties":{"summary":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["summary","tags"]}`),
)

Cost & token usage

Every run reports its cost and token usage. CostUSD is the dollar cost; Usage holds the token breakdown. Use Usage.TotalTokens() for the headline "tokens used" figure (input + output + cache read + cache create) instead of summing the fields by hand.

text, result, err := claudecli.RunText(ctx, "Say hello")
// ...
fmt.Printf("cost $%.4f for %d tokens\n", result.CostUSD, result.Usage.TotalTokens())
fmt.Println(result.Usage) // Usage{in: 12, out: 5, cacheRead: 0, cacheCreate: 0, total: 17}

The same fields are on BlockingResult (from RunBlocking) and on each *ResultEvent in streaming mode. The SDK reports cost and usage per call and holds no running total — accumulating across runs is the caller's concern.

For a per-model breakdown (including context window and web search/fetch counts), read ResultEvent.ModelUsage, keyed by model ID; each entry has its own CostUSD and TotalTokens().

Client with defaults

client := claudecli.New(
    claudecli.WithModel(claudecli.ModelSonnet),
    claudecli.WithPermissionMode(claudecli.PermissionPlan),
    claudecli.WithMaxBudget(0.50),
)

// All calls inherit these defaults
stream := client.Run(ctx, "Review this code")

// Per-call overrides replace defaults
stream := client.Run(ctx, "Quick check",
    claudecli.WithModel(claudecli.ModelHaiku),
)

Authentication

Check, login, and logout via the CLI's auth subcommands.

// Check current auth state (three-state: authenticated/unauthenticated/unknown)
status, err := client.AuthStatus(ctx)
fmt.Println(status.Status, status.Email, status.OrgName)

// Start OAuth login — returns URL for user to visit
proc, err := client.AuthLogin(ctx,
    claudecli.WithNoBrowser(), // required for SubmitCode
)
// Show AutoOpenURL to the user (localhost redirect).
// After authorizing, the browser redirects to localhost which fails on remote
// machines. User copies the failed redirect URL and passes it to SubmitCode.
fmt.Println("Visit:", proc.AutoOpenURL)

// User pastes the redirect URL (http://localhost:PORT/callback?code=X&state=Y):
err = proc.SubmitCode(redirectURL)

err = proc.Wait() // blocks until login completes

// Logout
err = client.AuthLogout(ctx)

Package-level shortcuts (AuthStatus, AuthLogin, AuthLogout) use the default client. Use NewClient([]ClientOption{WithLogger(logger)}) for debug logging.

Stream state

Poll the stream's lifecycle state at any time:

stream := client.Run(ctx, prompt)

// State is tracked automatically as events flow
stream.State() // StateStarting -> StateRunning -> StateDone/StateFailed

// Block until completion
result, err := stream.Wait() // idempotent, safe to call multiple times

States: StateStarting, StateRunning, StateDone, StateFailed.

Session lifecycle differs: StateStarting → StateIdle (after Connect) → StateRunning (during Query) → StateIdle (after result) → StateDone (after Close).

Activity state (watchdogs)

Lifecycle state tells you what phase the session is in; activity state tells you what the CLI is doing right now. For watchdogs that time out on event silence, use activity state to distinguish "model is generating" from "CLI is executing a tool" from "between turns":

for ev := range session.Events() {
    if cs, ok := ev.(*CLIStateChangeEvent); ok {
        // cs.State is one of:
        //   ActivityIdle              — between turns
        //   ActivityThinking          — model is generating
        //   ActivityAwaitingToolResult — a top-level tool_use is outstanding
        resetTimer(cs.State)
    }
}

info := session.ProcessInfo() // {LastStdoutAt, ActivityState, Lifecycle, SessionID}

CLIStateChangeEvent is emitted immediately BEFORE the event that triggered the transition (e.g. before the first ToolUseEvent of a turn), so consumers can update their state before processing the triggering event. ProcessInfo().LastStdoutAt is stamped from the stdout scanner independent of parsed events, so a stall can be distinguished from a quiet turn without inferring it from ToolUseEvent/ToolResultEvent pairing.

While the session sits in ActivityAwaitingToolResult, a ToolProgressEvent is emitted every 30 s carrying the first pending top-level tool_use's ToolUseID, ToolName, and Elapsed since it started. This is a pushed liveness signal for long tool runs — consumers can render "Bash running for 4m 12s" directly without polling ProcessInfo() or computing elapsed time themselves. Parallel tool_use calls do not change the reported tool; the first one is stable until the awaiting state ends.

Sessions

// Resume a previous session
stream := client.Run(ctx, "Continue where we left off",
    claudecli.WithSessionID("sess-abc123"),
)

// Fork from an existing session
stream := client.Run(ctx, "Try a different approach",
    claudecli.WithSessionID("sess-abc123"),
    claudecli.WithForkSession(),
)

// Continue the most recent session
stream := client.Run(ctx, "What were we doing?",
    claudecli.WithContinue(),
)

Agents

// Use a named agent
stream := client.Run(ctx, "Review this PR",
    claudecli.WithAgent("reviewer"),
)

// Define custom agents inline
stream := client.Run(ctx, "Check the code",
    claudecli.WithAgentDef(`{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}`),
    claudecli.WithAgent("reviewer"),
)

Interactive sessions

Connect() starts a bidirectional session with the CLI's control protocol. Supports multi-turn conversations, programmatic tool permission callbacks, and mid-session model/permission changes.

session, err := client.Connect(ctx,
    claudecli.WithModel(claudecli.ModelSonnet),
    claudecli.WithCanUseTool(func(name string, input json.RawMessage) (*claudecli.PermissionResponse, error) {
        if name == "Bash" {
            return &claudecli.PermissionResponse{Allow: false, DenyMessage: "no shell"}, nil
        }
        return &claudecli.PermissionResponse{Allow: true}, nil
    }),
)
if err != nil {
    log.Fatal(err)
}
defer session.Close()

// Send queries
session.Query("What files are in this directory?")

// Read events
for event := range session.Events() {
    switch e := event.(type) {
    case *claudecli.TextEvent:
        fmt.Print(e.Content)
    case *claudecli.ResultEvent:
        fmt.Printf("\nDone: $%.4f\n", e.CostUSD)
    }
}

// Or block until completion
result, err := session.Wait()

Session methods:

• Query(prompt) — send a text-only user message (sets up result tracking for Wait())
• QueryWithContent(prompt, blocks...) — send a message with text and multimodal content blocks
• SendMessage(prompt) — send a message without result tracking (can be called mid-turn)
• SendMessageWithContent(prompt, blocks...) — multimodal variant of SendMessage
• Events() — event channel
• Wait() — block until result (idempotent)
• Interrupt() — send interrupt signal
• Ping(timeout) — round-trip a no-op control request to prove the CLI's read loop is alive (not just that the process is running). Watchdog-friendly: any CLI response, including "unknown subtype", counts as success
• SetPermissionMode(mode) — change permissions mid-session
• SetModel(model) — change model mid-session
• GetServerInfo() — raw JSON from the initialize handshake
• RewindFiles(userMessageID) — rewind files to a checkpoint
• ReconnectMCPServer(name) — reconnect a named MCP server (non-blocking)
• ReconnectMCPServerWait(name, timeout) — reconnect and block until connected (polls mcp_status; 0 timeout = 10s default)
• ToggleMCPServer(name, enabled) — enable/disable an MCP server
• StopTask(taskID) — stop a running task
• GetMCPStatus() — query MCP server status (fire-and-forget)
• QueryMCPStatus() — query MCP server status, returns []MCPServerStatus
• Close() — terminate session

Mid-turn message injection

Query rejects while a turn is running ("query already in progress") because it manages result tracking for Wait(). Use SendMessage to inject a message mid-turn — it writes directly to stdin without state gating:

session.Query("Refactor the auth module")

// Later, while the agent is still working:
session.SendMessage("Also update the tests")

The CLI receives the message immediately but processes it at a safe boundary (between tool calls, not mid-generation). The injected message is folded into the current turn — the next ResultEvent from Wait() covers both the original query and injected messages.

SendMessage does not set up result tracking. If called without a prior Query, Wait() will hang. Use Query to start a turn, SendMessage to inject into it.

Concurrency: writes to stdin are mutex-serialized, so concurrent SendMessage calls are safe. Under extreme write volume the OS pipe buffer (64KB on Linux) provides natural backpressure — SendMessage blocks until the CLI drains stdin. If the pipe fills while the CLI is waiting for a control response (permission prompt), this could theoretically deadlock. In practice this requires dozens of queued messages and is unlikely for normal usage patterns.

Delivery confirmation: by default, SendMessage is fire-and-forget — you write to stdin with no acknowledgment. Enable WithReplayUserMessages() to have the CLI echo each user message back on stdout as a UserEvent with IsReplay=true. This confirms the CLI has read and accepted the message:

session, err := client.Connect(ctx,
    claudecli.WithReplayUserMessages(),
)

session.Query("Start the refactor")
session.SendMessage("Also update the tests")

for event := range session.Events() {
    switch e := event.(type) {
    case *claudecli.UserEvent:
        if e.IsReplay {
            fmt.Printf("CLI confirmed: %s\n", e.Text())
        }
    }
}

Forking an existing session

WithForkSession paired with WithResume / WithContinue / WithSessionID runs the CLI against a new session ID seeded with the parent's full history. The parent's session file on disk is not modified. Useful for asking a one-off question against a live session's context without polluting its transcript:

result, err := client.RunBlocking(ctx, "Summarize this session in 2-4 words.",
    claudecli.WithResume(parentSessionID),
    claudecli.WithForkSession(),
    claudecli.WithModel(claudecli.ModelHaiku),
)
// result.SessionID is the fork's new ID (unique from parentSessionID).
// The parent session file on disk is byte-for-byte unchanged.

Prompt-cache hits on the shared prefix keep forks cheap. The fork writes its own session file to disk — callers that fork repeatedly should plan to clean these up. The parent must have been persisted (started via Connect, WithSessionID, WithResume, or WithContinue; RunBlocking without any of those defaults to --no-session-persistence).

User input (AskUserQuestion)

When Claude calls the AskUserQuestion tool, it arrives as a can_use_tool control request. Use WithUserInput to handle these with a dedicated callback instead of routing them through WithCanUseTool:

session, err := client.Connect(ctx,
    claudecli.WithUserInput(func(questions []claudecli.Question) (map[string]string, error) {
        answers := make(map[string]string)
        for _, q := range questions {
            // Present q.Header, q.Question, q.Options to your UI
            answers[q.Question] = getUserSelection(q)
        }
        return answers, nil
    }),
    claudecli.WithCanUseTool(func(name string, input json.RawMessage) (*claudecli.PermissionResponse, error) {
        return &claudecli.PermissionResponse{Allow: true}, nil
    }),
)

Routing rules:

• Both registered: AskUserQuestion → userInput, other tools → canUseTool
• Only WithCanUseTool: AskUserQuestion falls through to canUseTool (backward compatible)
• Only WithUserInput: AskUserQuestion → userInput, other tools get error response

Multi-session pool

Pool is a registry that tracks multiple sessions and multiplexes their events into a single channel, tagged by session ID. The pool is purely additive — it doesn't modify Session or Client APIs.

pool := claudecli.NewPool()
defer pool.Close()

s1, _ := client.Connect(ctx)
s1.Query("start task A")
// Wait for InitEvent so SessionID is set...

s2, _ := client.Connect(ctx)
s2.Query("start task B")

pool.Add(s1, claudecli.SessionMeta{Name: "task-a", Labels: map[string]string{"role": "worker"}})
pool.Add(s2, claudecli.SessionMeta{Name: "task-b"})

// Single event loop for all sessions
for pe := range pool.Events() {
    fmt.Printf("[%s] %T\n", pe.SessionID, pe.Event)
}

Pool methods: Add, Remove, Get, List, Events, Close, CloseAll. All are thread-safe. CloseAll closes every registered session in parallel (respecting each session's grace period), then closes the pool — useful for clean application shutdown.

Inter-agent messaging

FormatAgentMessage wraps content in a structured format that Claude recognizes as peer communication. Pool.SendAgentMessage is a convenience that looks up sessions and calls SendMessage on the target.

// Direct formatting
msg := claudecli.FormatAgentMessage("task-a", "I finished the auth refactor")
session.SendMessage(msg)

// Via pool — uses sender's SessionMeta.Name automatically
pool.SendAgentMessage(s1.SessionID(), s2.SessionID(), "I finished the auth refactor")

Typed Agent tool input

When a session spawns a sub-agent, the ToolUseEvent has Name: "Agent". Use ParseAgentInput() to extract structured fields without manual JSON parsing:

case *claudecli.ToolUseEvent:
    if agent := e.ParseAgentInput(); agent != nil {
        fmt.Printf("Agent: %s (%s) — %s\n", agent.Name, agent.SubagentType, agent.Description)
        if agent.Isolation == "worktree" {
            fmt.Println("  running in isolated git worktree")
        }
    }

AgentInput fields: Description, Prompt, SubagentType, Name, RunInBackground, Model, Isolation ("worktree" for git worktree isolation), Mode (permission mode: "plan", "acceptEdits", etc.), TeamName (team name for spawning).

Subagent activity tracking

UserEvent makes subagent execution visible. Use ParentToolUseID to correlate events with their parent Agent tool call, and AgentResult to detect completion:

case *claudecli.UserEvent:
    if e.ParentToolUseID != "" {
        // This event belongs to the subagent spawned by that Agent tool call.
        fmt.Printf("  [subagent %s] tool result\n", e.ParentToolUseID)
    }
    if e.AgentResult != nil {
        fmt.Printf("  Agent %s (%s) completed: %d tokens, %dms, %d tool calls\n",
            e.AgentResult.AgentID, e.AgentResult.AgentType,
            e.AgentResult.TotalTokens, e.AgentResult.TotalDurationMs,
            e.AgentResult.TotalToolUseCount)
    }
case *claudecli.TaskEvent:
    // Real-time subagent lifecycle: task_started → task_progress → task_notification
    fmt.Printf("  [task %s] %s (tokens: %d, tools: %d, %dms)\n",
        e.Subtype, e.Description, e.TotalTokens, e.ToolUses, e.DurationMs)
case *claudecli.ToolUseEvent:
    if e.ParentToolUseID != "" {
        fmt.Printf("  [subagent] tool: %s\n", e.Name) // from a subagent
    } else {
        fmt.Printf("[tool: %s]\n", e.Name) // top-level
    }

Dynamic workflows

Dynamic workflows orchestrate many subagents from a script the CLI runtime runs in the background. There is no new flag or API to trigger one — it is prompt content: include ultracode, ask in your own words ("run a workflow…"), or invoke a saved/bundled command like /deep-research. In headless mode (-p) the run starts automatically.

A workflow surfaces through the ordinary event stream as a single synthetic task with TaskType == "local_workflow". The run is a two-turn lifecycle that emits two ResultEvents: the first says the workflow is running in the background, the second (after it completes) carries the real answer — so take the last ResultEvent, not the first.

for event := range stream.Events() {
    switch e := event.(type) {
    case *claudecli.UserEvent:
        if wl := e.WorkflowLaunch; wl != nil {
            fmt.Printf("workflow %q launched (run %s)\n", wl.WorkflowName, wl.RunID)
        }
    case *claudecli.TaskEvent:
        if e.IsWorkflow() {
            for _, p := range e.WorkflowProgress { // per-phase / per-agent state
                if p.IsAgent() {
                    fmt.Printf("  [%s] %s: %s (%d tok)\n", p.PhaseTitle, p.Label, p.State, p.Tokens)
                }
            }
        }
    case *claudecli.ResultEvent:
        fmt.Println("answer:", e.Text) // keep the LAST one
    }
}

The CLI stamps task_type only on the task_started event; the later task_progress, task_updated, and task_notification events for the same task omit it. The SDK backfills TaskType and WorkflowName from the matching task_started, so IsWorkflow() and WorkflowName stay correct across the whole lifecycle — you can gate on IsWorkflow() for progress and the terminal task_notification too, not just the launch.

Monitoring out-of-band

The runtime also persists live run state on disk keyed by RunID (it survives the SDK's --no-session-persistence). Given a WorkflowLaunch, you can monitor the run from a separate goroutine without consuming the event stream:

launch := userEvent.WorkflowLaunch
snaps, err := claudecli.WatchWorkflow(ctx, launch,
    claudecli.WithPollInterval(time.Second))
for snap := range snaps { // closes on terminal status (completed/stopped/killed)
    fmt.Printf("%s: %d/%d agents, %d tokens\n",
        snap.Status, len(snap.Agents()), snap.AgentCount, snap.TotalTokens)
}

// Or a one-shot read (e.g. to fetch the final Result after completion):
snap, err := claudecli.ReadWorkflowSnapshot(launch)

WorkflowLaunch.ManifestPath() / JournalPath() expose the underlying file paths. This reads an undocumented internal CLI layout that may change between versions, so it degrades gracefully (transient read/parse errors are retried; Raw preserves the full manifest). The in-stream WorkflowProgress carries the same live data, so the filesystem path is a complement for out-of-band or fire-and-forget monitoring, not a requirement.

Multimodal input

Send images and documents alongside text in interactive sessions:

imgData, _ := os.ReadFile("screenshot.png")
session.QueryWithContent("Describe this image",
    claudecli.ImageBlock("image/png", imgData),
)

pdfData, _ := os.ReadFile("report.pdf")
session.QueryWithContent("Summarize this document",
    claudecli.DocumentBlock("application/pdf", pdfData),
)

Content block constructors: TextBlock, ImageBlock, DocumentBlock. Base64 encoding is handled internally.

Custom executor

The Executor interface controls how the CLI process is spawned. Implement it to run Claude in Docker, over SSH, or any other environment.

type Executor interface {
    Start(ctx context.Context, cfg *StartConfig) (*Process, error)
}

type StartConfig struct {
    Args                    []string
    Stdin                   io.Reader
    Env                     map[string]string
    WorkDir                 string
    KeepStdinOpen           bool
    EnableFileCheckpointing bool
}

// Example: run Claude inside a Docker container
type DockerExecutor struct {
    Image  string
    Mounts []string
}

func (d *DockerExecutor) Start(ctx context.Context, cfg *claudecli.StartConfig) (*claudecli.Process, error) {
    dockerArgs := []string{"run", "--rm", "-i", d.Image}
    dockerArgs = append(dockerArgs, "claude")
    dockerArgs = append(dockerArgs, cfg.Args...)
    cmd := exec.CommandContext(ctx, "docker", dockerArgs...)
    cmd.Stdin = cfg.Stdin
    if cfg.WorkDir != "" {
        cmd.Dir = cfg.WorkDir
    }
    // ... set up stdout/stderr pipes ...
    cmd.Start()
    return &claudecli.Process{
        Stdout: stdout,
        Stderr: stderr,
        Wait:   cmd.Wait,
    }, nil
}

client := claudecli.NewWithExecutor(&DockerExecutor{Image: "my-claude:latest"},
    claudecli.WithModel(claudecli.ModelSonnet),
)

Testing

Use FixtureExecutor to replay recorded JSONL streams without invoking the real CLI:

func TestMyFeature(t *testing.T) {
    exec, err := claudecli.NewFixtureExecutorFromFile("testdata/session.jsonl")
    if err != nil {
        t.Fatal(err)
    }
    client := claudecli.NewWithExecutor(exec)

    text, _, err := client.RunText(context.Background(), "ignored prompt")
    if err != nil {
        t.Fatal(err)
    }
    if text != "expected output" {
        t.Errorf("got %q", text)
    }
}

For testing interactive sessions, use BidiFixtureExecutor:

bidi := claudecli.NewBidiFixtureExecutor()
client := claudecli.NewWithExecutor(bidi)

go func() {
    // Simulate CLI responses on bidi.StdoutWriter
    // Read SDK requests from bidi.StdinReader
    bidi.StdoutWriter.Write([]byte(`{"type":"system","session_id":"test","model":"sonnet"}` + "\n"))
    bidi.StdoutWriter.Close()
}()

session, _ := client.Connect(ctx)

You can also parse JSONL directly:

ch := make(chan claudecli.Event, 64)
go func() {
    defer close(ch)
    claudecli.ParseEvents(ctx, reader, ch)
}()
for event := range ch {
    // ...
}

Event types

All events implement the sealed Event interface. Use type switches or type assertions.

Options

Options set at call time replace (not merge with) client-level defaults.

Error handling

import "errors"

text, _, err := client.RunText(ctx, prompt)

// Empty output (no text events received)
if errors.Is(err, claudecli.ErrEmptyOutput) { ... }

// Classify API errors with sentinel errors
if errors.Is(err, claudecli.ErrInvalidRequest) { ... }  // 400 bad request
if errors.Is(err, claudecli.ErrAuth) { ... }             // 401 authentication
if errors.Is(err, claudecli.ErrBilling) { ... }           // 402 billing/payment
if errors.Is(err, claudecli.ErrPermission) { ... }        // 403 permission denied
if errors.Is(err, claudecli.ErrNotFound) { ... }          // 404 not found
if errors.Is(err, claudecli.ErrRequestTooLarge) { ... }   // 413 request too large
if errors.Is(err, claudecli.ErrRateLimit) { ... }         // 429 rate limited
if errors.Is(err, claudecli.ErrAPI) { ... }               // 500 internal API error
if errors.Is(err, claudecli.ErrOverloaded) { ... }        // 529 API overloaded
if errors.Is(err, claudecli.ErrMaxTurns) { ... }          // max turns reached
if errors.Is(err, claudecli.ErrContextWindowExceeded) { ... } // context window exceeded

// Extract turn count from max turns errors
var mte *claudecli.MaxTurnsError
if errors.As(err, &mte) {
    fmt.Printf("hit max turns: %d\n", mte.Turns)
}

// Extract retry timing from rate limit errors
var rlErr *claudecli.RateLimitError
if errors.As(err, &rlErr) {
    time.Sleep(rlErr.RetryAfter)
}

// CLI process failure with exit code and stderr
// Error.Error() returns a concise message (auto-inferred from stderr patterns
// like "command not found", "permission denied", "no such file or directory").
// For full stderr, access the Stderr field directly.
// LastEvents contains the last 10 raw JSONL lines from stdout for post-mortem
// diagnostics when stderr and classified errors yield no information.
var cliErr *claudecli.Error
if errors.As(err, &cliErr) {
    fmt.Println(cliErr.ExitCode)
    fmt.Println(cliErr.Message)    // concise, auto-inferred from stderr
    fmt.Println(cliErr.Stderr)     // full stderr output
    fmt.Println(cliErr.LastEvents) // last 10 raw JSONL lines from stdout
}

// RunJSON/RunBlockingJSON failed to parse response as JSON
var ue *claudecli.UnmarshalError
if errors.As(err, &ue) {
    fmt.Println(ue.RawText) // original model output before fence stripping
}

Architecture

claudecli-go/
  doc.go         Package overview, thread safety, prerequisites
  event.go       Sealed Event interface, event types
  model.go       Model constants, EffortLevel constants (including DefaultEffort)
  permission.go  PermissionMode constants
  option.go      Functional options + CLI arg builder
  executor.go         Executor interface, LocalExecutor, FixtureExecutor, BidiFixtureExecutor
  executor_unix.go    Unix process group attrs (Setpgid, SIGTERM), stdbuf wrapping
  executor_windows.go Windows no-op platform attrs
  parse.go       JSONL stream parser (decoupled from process lifecycle)
  stream.go      Stream with State(), Events(), Next(), Wait(), Close()
  client.go      Client struct, Run/RunText/RunJSON/Connect, package-level shortcuts
  session.go     Interactive session with bidirectional control protocol
  control.go     Control message types, ContentBlock/ImageSource for multimodal input
  blocking.go    RunBlocking/RunBlockingJSON — non-streaming JSON output mode
  auth.go        AuthStatus (defensive three-state parsing), AuthLogin (BROWSER capture + localhost callback), AuthLogout, LoginProcess
  pool.go        Pool multi-session registry, FormatAgentMessage, SendAgentMessage
  version.go     sdkVersion (module version reported to CLI, build-info sourced), SDKVersion dev fallback, MinCLIVersion, CLI version checking with semver parsing
  internal.go    Stderr ring buffer, processExitError with heuristic inference, code fence stripping
  error.go       Sentinel errors (ErrInvalidRequest, ErrAuth, ErrBilling, ErrPermission, ErrNotFound, ErrRequestTooLarge, ErrRateLimit, ErrAPI, ErrOverloaded, ErrMaxTurns, ErrContextWindowExceeded), RateLimitError, MaxTurnsError, Error, UnmarshalError

Layers:

1. Parse (parse.go) — JSONL deserialization into typed events. Zero coupling to process execution. Testable with fixtures. Returns immediately after the result event to avoid blocking on CLI hang bugs.
2. Execute (executor.go, executor_{unix,windows}.go) — Executor interface abstracts process spawning. LocalExecutor handles the real CLI with platform-aware command construction: stdbuf -oL wrapping on Linux, npm .cmd shim bypass on Windows.
3. Client (client.go) — Composes executor + options. Builds CLI args, starts process synchronously, reads events in goroutine. Synthesizes ResultEvent if CLI exits without one. Connect() creates interactive sessions.
4. Session (session.go) — Bidirectional control protocol over stdin/stdout. Handles initialize handshake, control request routing (tool permissions), and multi-turn conversations. Connect() marks the session ready immediately after the initialize handshake (CLI 2.1.81+ defers the system init event until the first user message).
5. Blocking (blocking.go) — Non-streaming path using --output-format json. Simpler execution model for RunBlocking/RunBlockingJSON.

Known limitations / TODO

• JSONL format is unversioned — Claude CLI's stream-json output format is not formally versioned by Anthropic. Tested with Claude Code CLI 2.x. Breaking changes across CLI versions are possible.
• No retry/backoff — RateLimitEvent is emitted (with ResetsAt timestamp and RateLimitType) but the package does not automatically retry or backoff. Consumers must implement their own retry logic.
• stdbuf recommended on Linux — LocalExecutor uses stdbuf -oL for line-buffered stdout on Linux when available, falling back to direct execution without it.
• MCP server startup can be slow — The CLI waits for MCP server connections during the initialize handshake. With many MCP servers configured, this can take 30+ seconds. The WithInitTimeout option (default 60s) controls this; increase it if Connect() times out.
• WithExtraArgs validates reserved flags — Passing print, output-format, input-format, or verbose via WithExtraArgs panics at construction time to prevent conflicting CLI arguments.
• Blocking stderr capped at 10 MB — RunBlocking caps stderr collection at 10 MB. The streaming path uses a 1000-line ring buffer.
• Fork-session needs a persisted parent — RunBlocking by default emits --no-session-persistence, so the parent must be started with WithSessionID, WithResume/WithContinue, or via Connect for WithForkSession to find the parent on disk.
• AuthStatus fail-close — When the CLI exits 0 with non-JSON output, AuthStatus returns AuthStateUnknown (not AuthStateAuthenticated). Callers should handle this explicitly.
• Thinking text may be hidden — The CLI can emit ThinkingEvents with empty Content but a set Signature (the model thought, but the text was withheld). No SDK option changes this. Distinguish "thinking hidden" from "no thinking" via Content == "" && Signature != "".
• Workflows emit two ResultEvents — A dynamic workflow run produces two result events: the first reports it launched in the background, the second carries the real answer once it completes. Consume the last ResultEvent. A workflow also does not survive its parent CLI process (the run settles at status: "killed").
• Workflow on-disk state is an internal layout — WatchWorkflow/ReadWorkflowSnapshot read CLI run-state files (~/.claude/projects/.../workflows/<runId>.json) whose paths and JSON shape are undocumented and may change across CLI versions. They parse defensively and preserve Raw, but treat this as best-effort. File GC/lifetime is unverified.