The Problem

Building applications on top of GitHub Copilot Agent requires speaking JSON-RPC to the Copilot CLI and managing its process lifecycle. Doing this from scratch in each language means duplicating protocol handling, session state management, and tool-calling logic. This SDK standardizes that integration across four languages so teams don't reimplement the same client against an unstable, technical-preview protocol.

What This Does

copilot-sdk provides language-specific client libraries for Node.js/TypeScript (nodejs/), Python (python/), Go (go/), and .NET (dotnet/). Each SDK wraps the Copilot CLI's JSON-RPC server, handling session creation, message streaming, tool invocation, permission requests, and MCP server/agent configuration. All four share a common protocol version (sdk-protocol-version.json).

The repo also contains a shared test harness (test/harness/) with a replaying proxy that captures and replays CAPI traffic, plus 60+ YAML snapshots (test/snapshots/) that pin protocol behavior across all SDKs. Code generation scripts in nodejs/scripts/ produce the session event types and protocol version constants for each language.

How It Is Wired

Execution starts in each SDK's client class—nodejs/src/client.ts, python/copilot/client.py, go/client.go, dotnet/src/Client.cs. The client spawns or connects to the Copilot CLI process and communicates over JSON-RPC. The client module is the hub: nodejs/src/index.ts has 9 modules importing it (highest in the graph), and the session modules route all conversation state through it.

A typical flow: application calls session.send() → the session serializes the request → client sends JSON-RPC over stdio or TCP → the CLI processes it and streams events back. The session module (nodejs/src/session.ts, python/copilot/session.py, etc.) handles event callbacks, streaming deltas, and session resume. The test harness (test/harness/replayingCapiProxy.ts, 770 lines) sits between tests and the real CLI, recording and replaying traffic so tests run without a live Copilot instance.

The import graph shows no circular dependencies across 83 analyzed files. The main change-risk concentration is nodejs/src/index.ts (9 importers) and the test context modules (nodejs/test/e2e/harness/sdkTestContext, python/e2e/testharness/__init__)—changing their APIs ripples through every test file in that language.

How To Use It

Setup: Install the Copilot CLI per the README, then install your language's SDK:

# Node.js
npm install @github/copilot-sdk

# Python
pip install github-copilot-sdk

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

# .NET
dotnet add package GitHub.Copilot.SDK

Running it: The Node.js entry point is nodejs/src/index.ts; the Python equivalent is python/copilot/__init__.py. The basic example lives at nodejs/examples/basic-example.ts. Each SDK auto-manages the CLI process—no manual server setup required. Configuration is done programmatically (API keys, MCP servers, custom agents) via session creation options, not environment files.

Real-World Use

A customer-support bot that needs to answer questions using internal documentation. The application creates a Copilot session with an MCP server pointing at the docs index, registers a custom tool to look up ticket history, and streams responses back to the user. The permission handler intercepts any shell-command requests the model makes and routes them through an approval workflow.

Code Health & Issues

Static analysis found 34 issues: 3 high, 30 medium, 1 low.

  • High – Duplicated code blocks: 22 repeated 6-line blocks across 12 files, notably dotnet/src/Generated/SessionEvents.cs, nodejs/scripts/generate-csharp-session-types.ts, dotnet/src/SdkProtocolVersion.cs, and nodejs/scripts/update-protocol-version.ts. The code-generation scripts and their generated outputs share logic that should be DRYed.
  • High – Deep nesting: nodejs/src/session.ts, go/e2e/session_test.go, and nodejs/src/client.ts reach indentation depth 8; control flow is hard to follow. Flatten with early returns.
  • Medium – Oversized files: test/harness/replayingCapiProxy.ts (770 lines), nodejs/src/client.ts, and python/copilot/client.py carry too much responsibility.
  • Medium – Broad exception handling: python/copilot/session.py and python/copilot/client.py use bare except clauses that swallow errors indiscriminately.
  • Medium – High branching density: dotnet/src/Client.cs and dotnet/src/Session.cs have 184 branch points over 576 lines.
  • Low – TODO markers: 3 unresolved in dotnet/test/SessionTests.cs.

SDLC observations: tests and CI are present (GitHub Actions), license is MIT, no committed secrets detected. The test/snapshots/ YAML files act as a protocol contract—valuable but they will need regeneration whenever the CLI protocol changes.

The Bottom Line

This is a well-structured, multi-language SDK with strong test coverage and a clean module graph. The main liabilities are the code-generation duplication and the deep nesting in core session logic. Teams building on Copilot Agent should use it rather than rolling their own JSON-RPC client, but should expect breaking changes while it's in technical preview.