Go SDK: Deadlock in client.Start() when starting CLI via stdio

[djdefi]

Summary

The Go SDK deadlocks when calling client.Start() on macOS. The CLI works correctly when invoked directly, but the SDK's JSON-RPC communication over stdio fails.

Environment

• OS: macOS (Apple Silicon)
• Go version: 1.24
• SDK version: v0.0.0-20260115160841-b8a836b2c6a3 (pseudo-version from main)
• CLI version: 0.0.354 (Commit: 076bd172b)
• CLI path: /Users/djdefi/Library/Application Support/Code - Insiders/User/globalStorage/github.copilot-chat/copilotCli/copilot

Steps to Reproduce

package main

import (
    "log"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        LogLevel: "error",
    })
    
    // This deadlocks - never returns
    if err := client.Start(); err != nil {
        log.Fatal(err)
    }
    defer client.Stop()
    
    log.Println("Client started") // Never reached
}

Expected Behavior

client.Start() should either:

1. Successfully start the CLI and establish JSON-RPC communication
2. Return an error if communication fails

Actual Behavior

Program deadlocks with:

fatal error: all goroutines are asleep - deadlock!

goroutine 1 [select]:
github.com/github/copilot-sdk/go.(*JSONRPCClient).Request(...)
        jsonrpc.go:147
github.com/github/copilot-sdk/go.(*Client).Ping(...)
        client.go:730
github.com/github/copilot-sdk/go.(*Client).verifyProtocolVersion(...)
        client.go:753
github.com/github/copilot-sdk/go.(*Client).Start(...)
        client.go:239

Working CLI Test

The CLI works correctly when invoked directly:

$ copilot --log-level debug --allow-all-tools -p "hello"
Hello! I'm GitHub Copilot CLI, ready to help you with software engineering tasks...

Analysis

The deadlock occurs in verifyProtocolVersion() → Ping() → JSONRPCClient.Request(), suggesting the JSON-RPC channel setup over stdio isn't working correctly. The CLI starts but either:

1. Doesn't output the expected JSON-RPC responses
2. The SDK isn't reading them correctly
3. There's a timing issue in the startup sequence

Workaround

Currently using the mock client while investigating. Would appreciate any guidance on:

1. Required CLI flags for JSON-RPC mode
2. Environment variables for SDK communication
3. Alternative TCP mode configuration

Related

This is a follow-up discovery from #18 (Go submodule version tags). Found while trying to integrate the SDK into a project.

[github-actions]

Thanks for reporting this issue, @djdefi!

This is a well-documented bug report with excellent reproduction steps and stack traces. I've labeled this as sdk/go, bug, and priority/high since it's a blocking deadlock preventing SDK usage on macOS.

The issue appears to be in the JSON-RPC communication setup over stdio during client.Start(). The CLI works standalone but the SDK's JSON-RPC handshake isn't completing, causing the deadlock in verifyProtocolVersion().

This will need investigation into:

• Whether the CLI requires specific flags to enable JSON-RPC mode over stdio
• How the SDK is spawning and communicating with the CLI process
• Platform-specific stdio handling differences on macOS

The team will take a look at this soon!

AI generated by Issue Triage Agent

[djdefi]

Update: Root cause identified - Documentation gap, not a bug

After further investigation, I believe this is not a SDK bug but a documentation issue.

What I discovered

The npm @github/copilot package contains two different CLIs:

File	Supports --server --stdio
index.js (14MB bundled Node.js)	✅ YES
copilot-darwin-arm64/copilot (binary)	❌ NO

The confusion

I was using the binary from VS Code Insiders (copilot-chat/copilotCli/copilot) which lacks the --server --stdio flags. The SDK requires the index.js version.

Verified working

# Install the npm package
npm install @github/copilot@0.0.382

# Set CLI path to index.js (NOT the binary)
export COPILOT_CLI_PATH="$(pwd)/node_modules/@github/copilot/index.js"

# SDK now works!
go test -tags=integration -v ./pkg/copilot/...
# PASS!

Documentation gap

The SDK READMEs all say:

CLIPath (string): Path to CLI executable (default: "copilot")

But all SDK test harnesses explicitly use index.js:

• Go: ../nodejs/node_modules/@github/copilot/index.js
• Node.js: node_modules/@github/copilot/index.js
• Python: nodejs/node_modules/@github/copilot/index.js
• .NET: nodejs/node_modules/@github/copilot/index.js

Suggestion

Could this issue be converted to a documentation request to clarify:

1. SDK requires index.js, not the binary
2. The VS Code Insiders CLI binary is not compatible
3. Users should npm install @github/copilot and point to index.js

Apologies for the false positive! Happy to close this if you'd prefer to track documentation separately.

[anowardear062-svg]

Sure

[friggeri]

Thanks for reporting! @devm33 can you take a look?