GitHub Copilot SDK Go Instructions

Core Principles

- The SDK is in technical preview and may have breaking changes

- Requires Go 1.21 or later

- Requires GitHub Copilot CLI installed and in PATH

- Uses goroutines and channels for concurrent operations

- No external dependencies beyond the standard library

Installation

Always install via Go modules:

go get github.com/github/copilot-sdk/go

Client Initialization

Basic Client Setup

import "github.com/github/copilot-sdk/go"

client := copilot.NewClient(nil)
if err := client.Start(); err != nil {
    log.Fatal(err)
}
defer client.Stop()

Client Configuration Options

When creating a CopilotClient, use `ClientOptions`:

- `CLIPath` - Path to CLI executable (default: "copilot" from PATH)

- `CLIUrl` - URL of existing CLI server (e.g., "localhost:8080"). When provided, client won't spawn a process

- `Port` - Server port (default: 0 for random)

- `UseStdio` - Use stdio transport instead of TCP (default: true)

- `LogLevel` - Log level (default: "info")

- `AutoStart` - Auto-start server (default: true, use pointer: `boolPtr(true)`)

- `AutoRestart` - Auto-restart on crash (default: true, use pointer: `boolPtr(true)`)

- `Cwd` - Working directory for the CLI process

- `Env` - Environment variables for the CLI process ([]string)

Manual Server Control

For explicit control:

autoStart := false
client := copilot.NewClient(&copilot.ClientOptions{AutoStart: &autoStart})
if err := client.Start(); err != nil {
    log.Fatal(err)
}
// Use client...
client.Stop()

Use `ForceStop()` when `Stop()` takes too long.

Session Management

Creating Sessions

Use `SessionConfig` for configuration:

session, err := client.CreateSession(&copilot.SessionConfig{
	OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
    Model: "gpt-5",
    Streaming: true,
    Tools: []copilot.Tool{...},
    SystemMessage: &copilot.SystemMessageConfig{ ... },
    AvailableTools: []string{"tool1", "tool2"},
    ExcludedTools: []string{"tool3"},
    Provider: &copilot.ProviderConfig{ ... },
})
if err != nil {
    log.Fatal(err)
}

Session Config Options

- `SessionID` - Custom session ID

- `Model` - Model name ("gpt-5", "claude-sonnet-4.5", etc.)

- `Tools` - Custom tools exposed to the CLI ([]Tool)

- `SystemMessage` - System message customization (\*SystemMessageConfig)

- `AvailableTools` - Allowlist of tool names ([]string)

- `ExcludedTools` - Blocklist of tool names ([]string)

- `Provider` - Custom API provider configuration (BYOK) (\*ProviderConfig)

- `Streaming` - Enable streaming response chunks (bool)

- `MCPServers` - MCP server configurations

- `CustomAgents` - Custom agent configurations

- `ConfigDir` - Config directory override

- `SkillDirectories` - Skill directories ([]string)

- `DisabledSkills` - Disabled skills ([]string)

Resuming Sessions

session, err := client.ResumeSession("session-id", &copilot.ResumeSessionConfig{OnPermissionRequest: copilot.PermissionHandler.ApproveAll})
// Or with options:
session, err := client.ResumeSessionWithOptions("session-id", &copilot.ResumeSessionConfig{ ... })

Session Operations

- `session.SessionID` - Get session identifier (string)

- `session.Send(copilot.MessageOptions{Prompt: "...", Attachments: []copilot.Attachment{...}})` - Send message, returns (messageID string, error)

- `session.SendAndWait(options, timeout)` - Send and wait for idle, returns (\*SessionEvent, error)

- `session.Abort()` - Abort current processing, returns error

- `session.GetMessages()` - Get all events/messages, returns ([]SessionEvent, error)

- `session.Destroy()` - Clean up session, returns error

Event Handling

Event Subscription Pattern

ALWAYS use channels or done signals to wait for session events:

done := make(chan struct{})

unsubscribe := session.On(func(evt copilot.SessionEvent) {
    switch evt.Type {
    case copilot.AssistantMessage:
        fmt.Println(*evt.Data.Content)
    case copilot.SessionIdle:
        c