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

@github/copilot-sdk

npm install @github/copilot-sdk

github-copilot-sdk

pip install github-copilot-sdk

github.com/github/copilot-sdk/go

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

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:

Core Pattern: Client → Session → Message

All SDK usage follows: create a client, create a session, send messages.

Node.js / 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

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

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

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

Node.js

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

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

on(handler)

on(eventType, handler)

Call the returned function to unsubscribe. In .NET, call

.Dispose()

Custom Tools

Define tools that Copilot can call to extend its capabilities.

Node.js

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

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

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

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.

onPreToolUse

onPostToolUse

onUserPromptSubmitted

onSessionStart

onSessionEnd

onErrorOccurred

Pre-Tool Use Hook

Control tool permissions, modify arguments, or inject context before tool execution.

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:

permissionDecision

"allow"

"deny"

"ask"

permissionDecisionReason

modifiedArgs

additionalContext

suppressOutput

Post-Tool Use Hook

Transform results, redact sensitive data, or log tool activity after execution.

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.

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

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

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

async def on_pre_tool_use(input_data, invocation):
    if input_data["toolName"] in ["shell", "bash"]:
        return {"permissionDecision": "deny", "permissionDecisionReason": "Not permitted"}
    return {"permissionDecision": "allow"}

session = await client.create_session({
    "hooks": {"on_pre_tool_use": on_pre_tool_use}
})

Go Hook Example

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Hooks: &copilot.SessionHooks{
        OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
            return &copilot.PreToolUseHookOutput{PermissionDecision: "allow"}, nil
        },
    },
})

MCP Server Integration

Connect to MCP (Model Context Protocol) servers for pre-built tool capabilities.

Local Stdio Server

const session = await client.createSession({
    mcpServers: {
        filesystem: {
            type: "local",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
            tools: ["*"],
            env: { DEBUG: "true" },
            cwd: "./servers",
            timeout: 30000,
        },
    },
});

Remote HTTP Server

const session = await client.createSession({
    mcpServers: {
        github: {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/",
            headers: { Authorization: "Bearer ${TOKEN}" },
            tools: ["*"],
        },
    },
});

MCP Config Fields

Local/Stdio:

type

"local"

command

args

env

cwd

tools

["*"]

[]

timeout

Remote HTTP:

type

"http"

url

headers

tools

timeout

MCP Debugging

Test MCP servers independently before integrating:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

Use the MCP Inspector for interactive debugging:

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Common MCP issues:

• Tools not appearing → Set

  tools: ["*"]

  and verify server responds to

  tools/list

• Server not starting → Use absolute command paths, check

  cwd

• Stdout pollution → Debug output must go to stderr, not stdout

Authentication

Methods (Priority Order)

1. Explicit token —

   githubToken

   in constructor
2. HMAC key —

   CAPI_HMAC_KEY

   or

   COPILOT_HMAC_KEY

   env vars
3. Direct API token —

   GITHUB_COPILOT_API_TOKEN

   with

   COPILOT_API_URL

4. Environment variables —

   COPILOT_GITHUB_TOKEN

   →

   GH_TOKEN

   →

   GITHUB_TOKEN

5. Stored OAuth — From

   copilot auth login

6. GitHub CLI —

   gh auth

   credentials

Programmatic Token

const client = new CopilotClient({ githubToken: process.env.GITHUB_TOKEN });

OAuth GitHub App

For multi-user apps where users sign in with GitHub:

const client = new CopilotClient({
    githubToken: userAccessToken,    // gho_ or ghu_ token from OAuth flow
    useLoggedInUser: false,          // Don't use stored CLI credentials
});

Supported token types:

gho_

ghu_

github_pat_

ghp_

Disable Auto-Login

Prevent the SDK from using stored credentials:

const client = new CopilotClient({ useLoggedInUser: false });

BYOK (Bring Your Own Key)

Use your own API keys — no Copilot subscription required. The CLI acts as agent runtime only.

Provider Configurations

OpenAI:

provider: { type: "openai", baseUrl: "https://api.openai.com/v1", apiKey: process.env.OPENAI_API_KEY }

Azure AI Foundry (OpenAI-compatible):

provider: {
    type: "openai",
    baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // Use "responses" for GPT-5 series, "completions" for others
}

Azure OpenAI (native endpoint):

provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",  // Just the host — no /openai/v1
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: { apiVersion: "2024-10-21" },
}

Anthropic:

provider: { type: "anthropic", baseUrl: "https://api.anthropic.com", apiKey: process.env.ANTHROPIC_API_KEY }

Ollama (local):

provider: { type: "openai", baseUrl: "http://localhost:11434/v1" }

Provider Config Reference

type

"openai"

"azure"

"anthropic"

baseUrl

apiKey

bearerToken

wireApi

"completions"

"responses"

"completions"

azure.apiVersion

"2024-10-21"

Azure Managed Identity with BYOK

Use

DefaultAzureCredential

from azure.identity import DefaultAzureCredential
from copilot import CopilotClient, ProviderConfig, SessionConfig

credential = DefaultAzureCredential()
token = credential.get_token("https://cognitiveservices.azure.com/.default").token

session = await client.create_session(SessionConfig(
    model="gpt-4.1",
    provider=ProviderConfig(
        type="openai",
        base_url=f"{foundry_url}/openai/v1/",
        bearer_token=token,
        wire_api="responses",
    ),
))

Note: Bearer tokens expire (~1 hour). For long-running apps, refresh the token before each new session. The SDK does not auto-refresh tokens.

BYOK Limitations

• Static credentials only — no native Entra ID, OIDC, or managed identity support
• No auto-refresh — expired tokens require creating a new session
• Keys not persisted — must re-provide

  provider

  config on session resume
• Model availability — limited to what your provider offers

Session Persistence

Resume sessions across restarts by providing your own session ID.

// Create with explicit ID
const session = await client.createSession({
    sessionId: "user-123-task-456",
    model: "gpt-4.1",
});

// Resume later (even from a different client instance)
const resumed = await client.resumeSession("user-123-task-456");
await resumed.sendAndWait({ prompt: "What did we discuss?" });

Session Management

const sessions = await client.listSessions();           // List all
const lastId = await client.getLastSessionId();          // Get most recent
await client.deleteSession("user-123-task-456");         // Delete from storage
await session.destroy();                                 // Destroy active session

Resume Options

When resuming, you can reconfigure:

model

systemMessage

availableTools

excludedTools

provider

reasoningEffort

streaming

mcpServers

customAgents

skillDirectories

infiniteSessions

Session ID Best Practices

user-{userId}-{taskId}

user-alice-pr-review-42

tenant-{tenantId}-{workflow}

tenant-acme-onboarding

{userId}-{taskType}-{timestamp}

alice-deploy-1706932800

What Gets Persisted

Session state is saved to

~/.copilot/session-state/{sessionId}/

plan.md

files/

Infinite Sessions

For long-running workflows that may exceed context limits, enable auto-compaction:

const session = await client.createSession({
    infiniteSessions: {
        enabled: true,
        backgroundCompactionThreshold: 0.80,  // Start background compaction at 80%
        bufferExhaustionThreshold: 0.95,       // Block and compact at 95%
    },
});

Thresholds are context utilization ratios (0.0–1.0), not absolute token counts.

Custom Agents

Define specialized AI personas:

const session = await client.createSession({
    customAgents: [{
        name: "pr-reviewer",
        displayName: "PR Reviewer",
        description: "Reviews pull requests for best practices",
        prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
    }],
});

System Message

Control AI behavior and personality:

const session = await client.createSession({
    systemMessage: { content: "You are a helpful assistant. Always be concise." },
});

Skills Integration

Load skill directories to extend Copilot's capabilities:

const session = await client.createSession({
    skillDirectories: ["./skills/code-review", "./skills/documentation"],
    disabledSkills: ["experimental-feature"],
});

Skills can be combined with custom agents and MCP servers:

const session = await client.createSession({
    skillDirectories: ["./skills/security"],
    customAgents: [{ name: "auditor", prompt: "Focus on OWASP Top 10." }],
    mcpServers: { postgres: { type: "local", command: "npx", args: ["-y", "@modelcontextprotocol/server-postgres"], tools: ["*"] } },
});

Permission & Input Handlers

Handle tool permissions and user input requests programmatically. The SDK uses a deny-by-default permission model — all permission requests are denied unless you provide a handler.

const session = await client.createSession({
    onPermissionRequest: async (request) => {
        if (request.kind === "shell") {
            return { approved: request.command.startsWith("git") };
        }
        return { approved: true };
    },
    onUserInputRequest: async (request) => {
        return { response: "yes" };
    },
});

Token Usage Tracking

Subscribe to usage events instead of using CLI

/usage

session.on("assistant.usage", (event) => {
    console.log("Tokens:", { input: event.data.inputTokens, output: event.data.outputTokens });
});

Deployment Patterns

Local CLI (Default)

SDK auto-spawns CLI as subprocess. Simplest setup — zero configuration.

const client = new CopilotClient(); // Auto-manages CLI process

External CLI Server (Backend Services)

Run CLI in headless mode, connect SDK over TCP:

copilot --headless --port 4321

const client = new CopilotClient({ cliUrl: "localhost:4321" });

Multi-client support: Multiple SDK clients can share one CLI server.

Bundled CLI (Desktop Apps)

Ship CLI binary with your app:

const client = new CopilotClient({ cliPath: path.join(__dirname, "vendor", "copilot") });

Docker Compose

services:
  copilot-cli:
    image: ghcr.io/github/copilot-cli:latest
    command: ["--headless", "--port", "4321"]
    environment:
      - COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN}
    volumes:
      - session-data:/root/.copilot/session-state
  api:
    build: .
    environment:
      - CLI_URL=copilot-cli:4321
    depends_on: [copilot-cli]
volumes:
  session-data:

Session Isolation Patterns

Production Checklist

• Session cleanup: periodic deletion of expired sessions
• Health checks: ping CLI server, restart if unresponsive
• Persistent storage: mount

  ~/.copilot/session-state/

  for containers
• Secret management: use Vault/K8s Secrets for tokens
• Session locking: Redis or similar for shared session access
• Graceful shutdown: drain active sessions before stopping CLI

Client Configuration

cliPath

cliUrl

githubToken

useLoggedInUser

true

logLevel

"none"

"none"

"error"

"warning"

"info"

"debug"

autoRestart

true

useStdio

true

Session Configuration

model

"gpt-4.1"

"claude-sonnet-4"

sessionId

streaming

tools

mcpServers

hooks

provider

customAgents

systemMessage

skillDirectories

disabledSkills

reasoningEffort

availableTools

excludedTools

infiniteSessions

workingDirectory

SDK vs CLI Feature Comparison

✅ Available in SDK

Session management, messaging (

send

sendAndWait

abort

getMessages

❌ CLI-Only Features

Session export (

--share

/compact

infiniteSessions

/usage

/review

/delegate

Workarounds:

• Session export → Collect events manually with

  session.on()

  +

  session.getMessages()

• Permission control → Use

  onPermissionRequest

  handler instead of

  --allow-all-paths

• Context compaction → Use

  infiniteSessions

  config instead of

  /compact

Debugging

Enable debug logging:

const client = new CopilotClient({ logLevel: "debug" });

Custom log directory:

const client = new CopilotClient({ cliArgs: ["--log-dir", "/path/to/logs"] });

Common Issues

CLI not found

cliPath

Not authenticated

copilot auth login

githubToken

Session not found

destroy()

listSessions()

Connection refused

autoRestart: true

tools: ["*"]

Connection State

console.log("State:", client.getState());  // "connected" after start()
client.on("stateChange", (state) => console.log("Changed to:", state));

Key API Summary

new CopilotClient()

client.createSession()

session.sendAndWait()

client.resumeSession()

client.stop()

CopilotClient()

client.create_session()

session.send_and_wait()

client.resume_session()

client.stop()

copilot.NewClient(nil)

client.CreateSession()

session.SendAndWait()

client.ResumeSession()

client.Stop()

new CopilotClient()

client.CreateSessionAsync()

session.SendAndWaitAsync()

client.ResumeSessionAsync()

client.DisposeAsync()

References

• GitHub Copilot SDK
• Copilot CLI Installation
• MCP Protocol Specification
• MCP Servers Directory
• GitHub MCP Server