Skip to main content
Community Maintained - This SDK is functional but receives limited maintenance. For production use, we recommend the TypeScript SDK or Python SDK.
Contributions welcome! See the GitHub repository to contribute.

​
Client

The main client for interacting with Chucky in Go.

​
Installation

go get github.com/chucky-cloud/chucky-sdk-go

​
Import

import chucky "github.com/chucky-cloud/chucky-sdk-go"

​
Creating a Client

client := chucky.NewClient(chucky.ClientOptions{
    Token: "your-jwt-token",
    Debug: true,
})
defer client.Close()

​
ClientOptions

FieldTypeRequiredDefaultDescription
TokenstringYes-JWT authentication token
BaseURLstringNowss://conjure.chucky.cloud/wsWebSocket server URL
DebugboolNofalseEnable debug logging
Timeouttime.DurationNo60sConnection timeout
KeepAliveIntervaltime.DurationNo5mKeep-alive ping interval

​
Methods

​
CreateSession()

Create a new conversation session. 
func (c *Client) CreateSession(opts *SessionOptions) *Session

​
SessionOptions

FieldTypeDescription
ModelModelClaude model to use
SystemPromptanySystem prompt (string or preset)
MaxTurnsintMax conversation turns
MaxBudgetUsdfloat64Budget limit
ToolsanyAvailable tools
McpServers[]McpServerDefinitionMCP servers with tools
OutputFormat*OutputFormatStructured output format
SessionIDstringResume existing session
ForkSessionboolFork from session ID

​
Example

session := client.CreateSession(&chucky.SessionOptions{
    BaseOptions: chucky.BaseOptions{
        Model:    chucky.ModelClaudeSonnet,
        MaxTurns: 10,
    },
})
defer session.Close()

​
On()

Register event handlers. 
func (c *Client) On(handlers ClientEventHandlers) *Client

​
ClientEventHandlers

HandlerParametersDescription
OnConnect()WebSocket connected
OnDisconnect(reason string)WebSocket disconnected
OnSessionStart(sessionID string)Session started
OnSessionEnd(sessionID string)Session ended
OnError(err error)Error occurred

​
Example

client.On(chucky.ClientEventHandlers{
    OnConnect: func() {
        fmt.Println("Connected!")
    },
    OnError: func(err error) {
        fmt.Println("Error:", err)
    },
})

​
Close()

Close the client and all active sessions. 
func (c *Client) Close()

​
Token Management

​
CreateToken()

Create a JWT token for authentication. 
func CreateToken(opts CreateTokenOptions) (string, error)

​
CreateTokenOptions

FieldTypeRequiredDescription
UserIDstringYesUser identifier
ProjectIDstringYesProject ID
SecretstringYesHMAC secret key
BudgetTokenBudgetNoBudget limits
ExpiresInint64NoToken TTL in seconds (default: 3600)
Permissions*TokenPermissionsNoPermission restrictions

​
Example

token, err := chucky.CreateToken(chucky.CreateTokenOptions{
    UserID:    "user-123",
    ProjectID: "your-project-id",
    Secret:    "hk_live_your_secret_key",
    Budget: chucky.CreateBudget(chucky.CreateBudgetOptions{
        AIDollars:    5.0,
        ComputeHours: 1.0,
        Window:       chucky.BudgetWindowDay,
    }),
})
if err != nil {
    log.Fatal(err)
}

​
CreateBudget()

Create a budget from human-readable values. 
func CreateBudget(opts CreateBudgetOptions) TokenBudget

​
CreateBudgetOptions

FieldTypeDescription
AIDollarsfloat64AI budget in dollars (converted to microdollars)
ComputeHoursfloat64Compute budget in hours (converted to seconds)
WindowBudgetWindowBudget window (hour, day, week, month)
WindowStarttime.TimeWindow start time

​
Complete Example

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    chucky "github.com/chucky-cloud/chucky-sdk-go"
)

func main() {
    // Create token
    token, err := chucky.CreateToken(chucky.CreateTokenOptions{
        UserID:    "user-123",
        ProjectID: "your-project-id",
        Secret:    "hk_live_your_secret_key",
        Budget: chucky.CreateBudget(chucky.CreateBudgetOptions{
            AIDollars:    1.0,
            ComputeHours: 0.5,
            Window:       chucky.BudgetWindowHour,
            WindowStart:  time.Now(),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Create client
    client := chucky.NewClient(chucky.ClientOptions{
        Token: token,
        Debug: true,
    })
    defer client.Close()

    // Create session
    session := client.CreateSession(&chucky.SessionOptions{
        BaseOptions: chucky.BaseOptions{
            Model:    chucky.ModelClaudeSonnet,
            MaxTurns: 5,
        },
    })

    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    // Send message
    if err := session.Send(ctx, "What is 2 + 2?"); err != nil {
        log.Fatal(err)
    }

    // Stream response
    for msg := range session.Stream(ctx) {
        switch m := msg.(type) {
        case *chucky.SDKAssistantMessage:
            text := chucky.GetAssistantText(m)
            if text != "" {
                fmt.Println("Assistant:", text)
            }
        case *chucky.SDKResultMessage:
            fmt.Println("Result:", m.Result)
            fmt.Printf("Cost: $%.6f\n", m.TotalCostUsd)
        }
    }

    session.Close()
}