copilot-sdk

# GitHub Copilot SDK Build applications that programmatically interact with GitHub Copilot. The SDK wraps the Copilot CLI via JSON-RPC, providing session management, custom tools, hooks, MCP server integration, and streaming across Node.js, Python, Go, and .NET. ## Prerequisites - **GitHub Copilot CLI** installed and authenticated (`copilot --version`) - **GitHub Copilot subscription** (Individual, Business, or Enterprise) — not required for BYOK - **Runtime:** Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+ ## Installation | Language | Package | Install | |----------|---------|---------| | Node.js | `@github/copilot-sdk` | `npm install @github/copilot-sdk` | | Python | `github-copilot-sdk` | `pip install github-copilot-sdk` | | Go | `github.com/github/copilot-sdk/go` | `go get github.com/github/copilot-sdk/go` | | .NET | `GitHub.Copilot.SDK` | `dotnet add package GitHub.Copilot.SDK` | ## Architecture The SDK communicates with the Copilot CLI via JSON-RPC over stdio (default) or TCP. The CLI manages model calls, tool execution, session state, and MCP server lifecycle. ``` Your App → SDK Client → [stdio/TCP] → Copilot CLI → Model Provider ↕ MCP Servers ``` **Transport modes:** | Mode | Description | Use Case | |------|-------------|----------| | **Stdio** (default) | CLI as subprocess via pipes | Local dev, single process | | **TCP** | CLI as network server | Multi-client, backend services | --- ## Core Pattern: Client → Session → Message All SDK usage follows: create a client, create a session, send messages. ### Node.js / TypeScript ```typescript import { CopilotClient } from "@github/copilot-sdk"; const client = new CopilotClient(); const session = await client.createSession({ model: "gpt-4.1" }); const response = await session.sendAndWait({ prompt: "What is 2 + 2?" }); console.log(response?.data.content); await client.stop(); ``` ### Python ```python import asyncio from copilot import CopilotClient async def main(): client = CopilotClient() await client.start() session = await client.create_session({"model": "gpt-4.1"}) response = await session.send_and_wait({"prompt": "What is 2 + 2?"}) print(response.data.content) await client.stop() asyncio.run(main()) ``` ### Go ```go client := copilot.NewClient(nil) if err := client.Start(ctx); err != nil { log.Fatal(err) } defer client.Stop() session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"}) response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What is 2 + 2?"}) fmt.Println(*response.Data.Content) ``` ### .NET ```csharp await using var client = new CopilotClient(); await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" }); var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" }); Console.WriteLine(response?.Data.Content); ``` --- ## Streaming Responses Enable real-time output by setting `streaming: true` and subscribing to delta events. ### Node.js ```typescript const session = await client.createSession({ model: "gpt-4.1", streaming: true }); session.on("assistant.message_delta", (event) => { process.stdout.write(event.data.deltaContent); }); session.on("session.idle", () => console.log()); await session.sendAndWait({ prompt: "Tell me a joke" }); ``` ### Python ```python from copilot.generated.session_events import SessionEventType session = await client.create_session({"model": "gpt-4.1", "streaming": True}) def handle_event(event): if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA: sys.stdout.write(event.data.delta_content) sys.stdout.flush() if event.type == SessionEventType.SESSION_IDLE: print() session.on(handle_event) await session.send_and_wait({"prompt": "Tell me a joke"}) ``` ### Event Subscription | Method | Description | |--------|-------------| | `on(handler)` | Subscribe to all events; returns unsubscribe function | | `on(eventType, handler)` | Subscribe to specific event type (Node.js only) | Call the returned function to unsubscribe. In .NET, call `.Dispose()` on the returned disposable. --- ## Custom Tools Define tools that Copilot can call to extend its capabilities. ### Node.js ```typescript import { CopilotClient, defineTool } from "@github/copilot-sdk"; const getWeather = defineTool("get_weather", { description: "Get the current weather for a city", parameters: { type: "object", properties: { city: { type: "string", description: "The city name" } }, required: ["city"], }, handler: async ({ city }) => ({ city, temperature: "72°F", condition: "sunny" }), }); const session = await client.createSession({ model: "gpt-4.1", tools: [getWeather], }); ``` ### Python ```python from copilot.tools import define_tool from pydantic import BaseModel, Field class GetWeatherParams(BaseModel): city: str = Field(description="The city name") @define_tool(description="Get the current weather for a city") async def get_weather(params: GetWeatherParams) -> dict: return {"city": params.city, "temperature": "72°F", "condition": "sunny"} session = await client.create_session({"model": "gpt-4.1", "tools": [get_weather]}) ``` ### Go ```go type WeatherParams struct { City string `json:"city" jsonschema:"The city name"` } getWeather := copilot.DefineTool("get_weather", "Get weather for a city", func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) { return WeatherResult{City: params.City, Temperature: "72°F"}, nil }, ) session, _ := client.CreateSession(ctx, &copilot.SessionConfig{ Model: "gpt-4.1", Tools: []copilot.Tool{getWeather}, }) ``` ### .NET ```csharp using Microsoft.Extensions.AI; using System.ComponentModel; var getWeather = AIFunctionFactory.Create( ([Description("The city name")] string city) => new { city, temperature = "72°F" }, "get_weather", "Get the current weather for a city"); await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1", Tools = [getWeather], }); ``` ### Tool Requirements - Handler must return JSON-serializable data (not `undefined`) - Parameters must follow JSON Schema format - Tool description should clearly state when the tool should be used --- ## Hooks Intercept and customize session behavior at key lifecycle points. | Hook | Trigger | Use Case | |------|---------|----------| | `onPreToolUse` | Before tool executes | Permission control, argument modification | | `onPostToolUse` | After tool executes | Result transformation, logging, redaction | | `onUserPromptSubmitted` | User sends message | Prompt modification, filtering, context injection | | `onSessionStart` | Session begins (new or resumed) | Add context, configure session | | `onSessionEnd` | Session ends | Cleanup, analytics, metrics | | `onErrorOccurred` | Error happens | Custom error handling, retry logic, monitoring | ### Pre-Tool Use Hook Control tool permissions, modify arguments, or inject context before tool execution. ```typescript const session = await client.createSession({ hooks: { onPreToolUse: async (input) => { if (["shell", "bash"].includes(input.toolName)) { return { permissionDecision: "deny", permissionDecisionReason: "Shell access not permitted" }; } return { permissionDecision: "allow" }; }, }, }); ``` **Input fields:** `timestamp`, `cwd`, `toolName`, `toolArgs` **Output fields:** | Field | Type | Description | |-------|------|-------------| | `permissionDecision` | `"allow"` \| `"deny"` \| `"ask"` | Whether to allow the tool call | | `permissionDecisionReason` | string | Explanation for deny/ask | | `modifiedArgs` | object | Modified arguments to pass | | `additionalContext` | string | Extra context for conversation | | `suppressOutput` | boolean | Hide tool output from conversation | ### Post-Tool Use Hook Transform results, redact sensitive data, or log tool activity after execution. ```typescript hooks: { onPostToolUse: async (input) => { // Redact sensitive data from results if (typeof input.toolResult === "string") { let redacted = input.toolResult; for (const pattern of SENSITIVE_PATTERNS) { redacted = redacted.replace(pattern, "[REDACTED]"); } if (redacted !== input.toolResult) { return { modifiedResult: redacted }; } } return null; // Pass through unchanged }, } ``` **Output fields:** `modifiedResult`, `additionalContext`, `suppressOutput` ### User Prompt Submitted Hook Modify or enhance user prompts before processing. Useful for prompt templates, context injection, and input validation. ```typescript hooks: { onUserPromptSubmitted: async (input) => { return { modifiedPrompt: `[User from engineering team] ${input.prompt}`, additionalContext: "Follow company coding standards.", }; }, } ``` **Output fields:** `modifiedPrompt`, `additionalContext`, `suppressOutput` ### Session Lifecycle Hooks ```typescript hooks: { onSessionStart: async (input, invocation) => { // input.source: "startup" | "resume" | "new" console.log(`Session ${invocation.sessionId} started (${input.source})`); return { additionalContext: "Project uses TypeScript and React." }; }, onSessionEnd: async (input, invocation) => { // input.reason: "complete" | "error" | "abort" | "timeout" | "user_exit" await recordMetrics({ sessionId: invocation.sessionId, reason: input.reason }); return null; }, } ``` ### Error Handling Hook ```typescript hooks: { onErrorOccurred: async (input) => { // input.errorContext: "model_call" | "tool_execution" | "system" | "user_input" // input.recoverable: boolean if (input.errorContext === "model_call" && input.error.includes("rate")) { return { errorHandling: "retry", retryCount: 3, userNotification: "Rate limited. Retrying..." }; } return null; // Default error handling }, } ``` **Output fields:** `suppressOutput`, `errorHandling` (`"retry"` | `"skip"` | `"abort"`), `retryCount`, `userNotification` ### Python Hook Example ```python async def on_pre_tool_use(input_data, invocation): if input_data["toolName"] in ["shell", "bash"]: return {"permissionDecision": "deny", "permissionDecisionReason": "Not permitted"}