copilot-sdk Dissection

Complete reverse-engineering documentation of the GitHub Copilot CLI SDK (copilot-sdk) — a polyglot repository providing programmable SDKs in TypeScript, Python, Go, and C# for embedding Copilot's agentic workflows into applications.

Quick Facts

297
Source Files
4
SDK Languages
v3
Protocol Version
MIT
License
Property Value
Project copilot-sdk (GitHub Copilot CLI SDKs)
Repository github.com/github/copilot-sdk
Languages TypeScript 29% · Go 25% · Python 23% · C# 21%
Architecture Contract-First Polyglot SDK — JSON-RPC 2.0 over stdio/TCP to Copilot CLI
Status Technical Preview

Language Distribution

TypeScript
29%
Go
25%
Python
23%
C#
21%

Architecture At A Glance

Architecture At A Glance
flowchart TD
  A["Your Application"] --> B["SDK Client\nCopilotClient"]
  B --> C["Session(s)\nTools, Hooks, Permissions, MCP Servers"]
  C <-->|"JSON-RPC 2.0\n(stdio / TCP)"| D["Copilot CLI\nServer Process"]
  D --> E["LLM Inference\nTool Orchestration, Conversation State"]
Key Pattern

The SDK is a thin typed facade over JSON-RPC. All AI logic lives in the CLI process. The SDK manages:

  • Process lifecycle (spawn, connect, restart)
  • Session lifecycle (create, send, events, disconnect)
  • Callback dispatch (tools, permissions, hooks)
  • Type-safe API via schema-driven code generation

Documents

Foundation — What's here?

Foundation Documents
flowchart LR
  A["01 Discovery\nFile counts, language breakdown,\nproject identity, sampling strategy"] --> B["02 Structure\nDirectory tree, module map,\nSDK mirror pattern, dependency graph"]
  B --> C["03 Tech Stack\nLanguages, frameworks,\nbuild tools, package managers, CI/CD"]

Core Architecture — How does it work?

Core Architecture Documents
flowchart LR
  A["04 Entry Points\nPackage exports, client init,\nsession creation, bootstrap"] --> B["05 Architecture\nDesign patterns, state machines,\nevent system"]
  B --> C["06 Data Flow\nMessage flow, JSON-RPC protocol,\nstreaming events, tool flows"]
  C --> D["07 API Surface\nPublic API per SDK,\ntype system, cross-language comparison"]

Implementation Details — How is it built?

Implementation Documents
flowchart LR
  A["08 Conventions\nNaming, file organization,\nerror handling, async patterns"] --> B["09 Testing\nTest frameworks, E2E harness,\nreplay proxy, scenario system"]
  B --> C["10 Build & Deploy\njustfile orchestration, codegen,\nCLI bundling, CI/CD, publishing"]
  C --> D["11 Dependencies\nRuntime/dev deps per SDK,\nversion constraints, analysis"]

Security & Contribution — How do I work with it?

Operations Documents
flowchart LR
  A["12 Security Surface\nAuth model, token handling,\npermissions, process security, BYOK"] --> B["13 Contribution Guide\nDev setup, adding features,\nwriting tests, extending with tools"]

For AI Agents

AI Agent Reading Order

If you're an AI agent working with this codebase, start with:

  1. Structure — understand the 4-SDK mirror pattern
  2. Architecture — understand the Client/Session/RPC layers
  3. API Surface — cross-language API reference
  4. Contribution Guide Section 12 — AI-specific guidance from .github/copilot-instructions.md
Critical Rule

Any feature change must be implemented in ALL four SDKs (TypeScript, Python, Go, C#) with matching tests and codegen updates.

For Humans

Human Reading Order

If you're learning this codebase, recommended reading order:

  1. Discovery — "What am I looking at?"
  2. Entry Points — "How do I use it?" (includes sample code)
  3. Data Flow — "How does a message flow end-to-end?"
  4. Architecture — "What patterns does it use?"
  5. Build & Deploy — "How do I build and test it?"

Generated by the Dissector Agent — 13-phase codebase reverse-engineering system

Codebase path: C:\Users\tahaa\.copilot\repos\copilot-sdk

Analysis date: 2026-03-12