Go SDK

Backend services, devops tools, anything written in Go.

LiveSDKchirp login

Zero-dependency Go package modeled after the Python SDK's @track decorator. `chirp.Track(ctx, opts, fn)` opens an activity, runs your function, and closes the activity - outcome inferred from the returned error. Cancellation propagates through the context: cancel the parent context and the activity closes orange (canceled).

Single binary deployments love this - Chirp's only dep is the standard library, so it cross-compiles to anything Go does and adds about 60KB to a `go build`. Plays well with errgroup, with cobra-style CLIs, and with worker pools.

Prerequisites

Go 1.21+ (uses `slog` and structured errors).
A Chirp account.

Setup

1
Install the SDK
Standard go get. The module path matches the GitHub repo.
shell
```
go get github.com/BradyMeighan/ChirpApp/go-sdk
```
2
Pair your laptop
chirp login writes credentials to ~/.chirp/credentials. The SDK reads it on first call.
shell
```
chirp login
```

Wrap your work in chirp.Track

Three arguments: a context (for cancellation), AgentOptions (name + theme + schema), and the function to run. Whatever the function returns becomes the activity outcome - nil error → success, non-nil → failure (with the error message on the card).

main.go

package main

import (
    "context"
    "log/slog"
    "os/signal"
    "syscall"

    chirp "github.com/BradyMeighan/ChirpApp/go-sdk"
)

func main() {
    ctx, stop := signal.NotifyContext(context.Background(),
        syscall.SIGINT, syscall.SIGTERM)
    defer stop()

    err := chirp.Track(ctx, chirp.AgentOptions{
        Name:   "nightly-backup",
        Schema: "@agent",
        Theme:  "#22c55e",
    }, func(a *chirp.Agent) error {
        a.Update(ctx, "dumping postgres")
        if err := dumpPostgres(ctx); err != nil { return err }

        a.Update(ctx, "uploading to s3")
        return uploadToS3(ctx)
    })

    if err != nil {
        slog.Error("backup failed", "err", err)
    }
}

(Optional) Manual lifecycle for streaming work

When you don't have a single function to wrap (e.g. a long-lived worker that processes messages forever), use the manual API: chirp.Start returns an *Agent, then agent.Update and agent.End.

shell

agent, err := chirp.Start(ctx, chirp.AgentOptions{Name: "queue-worker"})
defer agent.End(ctx, chirp.OutcomeSuccess)

for msg := range queue {
    agent.Update(ctx, "processing "+msg.ID)
    if err := process(msg); err != nil {
        agent.End(ctx, chirp.OutcomeFailure)
        return
    }
}

What you’ll see

Card header: Go gopher logo + "Go · WORKING" + agent name. Action line shows the most recent `Update()` argument. Closes green on nil-return, red on non-nil error (with the error string), orange when the parent context is canceled (e.g. user hits Ctrl-C). The cancellation case is the killer feature - most SDKs hang the activity when you SIGINT, the Go SDK closes it cleanly.

Troubleshooting

context deadline exceeded errors after 30s.: The SDK uses the passed context for HTTP calls. If your context has a tight deadline, the activity post inherits it. Pass a longer-lived context or a fresh context.Background() if you want updates to outlive the wrapped function's deadline.
Updates from goroutines don't show up.: Pass the same *chirp.Agent into the goroutine - the agent is goroutine-safe. Don't call chirp.Track inside a goroutine and expect to update from outside; each Track call is a separate activity.
Compile error about Go version.: SDK uses Go 1.21's log/slog. Bump your go.mod to go 1.21 or pin to an older SDK release (go-sdk v0.3.x works on Go 1.19+).

Browse all integrations