GitHub Copilot SDK Node.js Instructions

Core Principles

- The SDK is in technical preview and may have breaking changes

- Requires Node.js 18.0 or later

- Requires GitHub Copilot CLI installed and in PATH

- Built with TypeScript for type safety

- Uses async/await patterns throughout

- Provides full TypeScript type definitions

Installation

Always install via npm/pnpm/yarn:

npm install @github/copilot-sdk
# or
pnpm add @github/copilot-sdk
# or
yarn add @github/copilot-sdk

Client Initialization

Basic Client Setup

import { CopilotClient, approveAll } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();
// Use client...
await client.stop();

Client Configuration Options

When creating a CopilotClient, use `CopilotClientOptions`:

- `cliPath` - Path to CLI executable (default: "copilot" from PATH)

- `cliArgs` - Extra arguments prepended before SDK-managed flags (string[])

- `cliUrl` - URL of existing CLI server (e.g., "localhost:8080"). When provided, client won't spawn a process

- `port` - Server port (default: 0 for random)

- `useStdio` - Use stdio transport instead of TCP (default: true)

- `logLevel` - Log level (default: "debug")

- `autoStart` - Auto-start server (default: true)

- `autoRestart` - Auto-restart on crash (default: true)

- `cwd` - Working directory for the CLI process (default: process.cwd())

- `env` - Environment variables for the CLI process (default: process.env)

Manual Server Control

For explicit control:

const client = new CopilotClient({ autoStart: false });
await client.start();
// Use client...
await client.stop();

Use `forceStop()` when `stop()` takes too long.

Session Management

Creating Sessions

Use `SessionConfig` for configuration:

const session = await client.createSession({
    onPermissionRequest: approveAll,
    model: "gpt-5",
    streaming: true,
    tools: [...],
    systemMessage: { ... },
    availableTools: ["tool1", "tool2"],
    excludedTools: ["tool3"],
    provider: { ... }
});

Session Config Options

- `sessionId` - Custom session ID (string)

- `model` - Model name ("gpt-5", "claude-sonnet-4.5", etc.)

- `tools` - Custom tools exposed to the CLI (Tool[])

- `systemMessage` - System message customization (SystemMessageConfig)

- `availableTools` - Allowlist of tool names (string[])

- `excludedTools` - Blocklist of tool names (string[])

- `provider` - Custom API provider configuration (BYOK) (ProviderConfig)

- `streaming` - Enable streaming response chunks (boolean)

- `mcpServers` - MCP server configurations (MCPServerConfig[])

- `customAgents` - Custom agent configurations (CustomAgentConfig[])

- `configDir` - Config directory override (string)

- `skillDirectories` - Skill directories (string[])

- `disabledSkills` - Disabled skills (string[])

- `onPermissionRequest` - Permission request handler (PermissionHandler)

Resuming Sessions

const session = await client.resumeSession("session-id", {
  tools: [myNewTool],
  onPermissionRequest: approveAll,
});

Session Operations

- `session.sessionId` - Get session identifier (string)

- `await session.send({ prompt: "...", attachments: [...] })` - Send message, returns Promise<string>

- `await session.sendAndWait({ prompt: "..." }, timeout)` - Send and wait for idle, returns Promise<AssistantMessageEvent | null>

- `await session.abort()` - Abort current processing

- `await session.getMessages()` - Get all events/messages, returns Promise<SessionEvent[]>

- `await session.destroy()` - Clean up session

Event Handling

Event Subscription Pattern

ALWAYS use async/await or Promises for waiting on session events:

await new Promise<void>((resolve) => {
  session.on((event) => {
    if (event.type === "assistant.message") {
      console.log(event.data.content);
    } else if (event.type === "session.idle") {
      resolve();
    }
  });

  session.send({ prompt: "..." });
});

Unsubscribing from