GitHub Copilot SDK

The GitHub Copilot SDK provides several session hooks that allow you to intercept and modify different stages of a Copilot session. These hooks enable you to implement custom logic for tool usage, message filtering, session management, and error handling.

Available hook categories include:

• Pre-tool use: Intercept tool calls to approve, deny, or modify them.
• Post-tool use: Transform the results returned by tools before they reach the model.
• User prompt submitted: Modify or filter user messages before they are processed.
• Session lifecycle: Manage logic triggered at the start and end of a session.
• Error handling: Implement custom logic for handling errors during a session.

Hooks are callbacks registered during session creation that allow you to inject custom logic into the Copilot conversation lifecycle. They can be used for permissions, auditing, notifications, and modifying session behavior without changing the core agent.

All hooks are optional. To continue with the default SDK behavior, return null (or the language equivalent) from the hook handler.

Session hooks allow you to intercept and customize Copilot session behavior at various points in the conversation lifecycle. You can use them to:

• Control tool execution: Approve, deny, or modify tool calls.
• Transform results: Modify tool outputs before they are processed.
• Add context: Inject additional information at the start of a session.
• Handle errors: Implement custom error handling logic.
• Audit and log: Track interactions for compliance and monitoring.

In addition to the official SDKs, there are community-maintained versions available for Clojure and C++.

Warning: These are unofficial, community-driven SDKs and are not supported by GitHub. Use them at your own risk.

| SDK         | Location                                                 |
| ----------- | -------------------------------------------------------- |
| **Clojure** | [copilot-community-sdk/copilot-sdk-clojure][sdk-clojure] |
| **C++**     | [0xeb/copilot-sdk-cpp][sdk-cpp]                          |

By default, the SDK exposes the Copilot CLI's first-party tools (similar to running the CLI with --allow-all).

• Tool Control: Tool execution is governed by the SDK's permission handler. You can approve, deny, or customize tool calls.
• Configuration: You can enable or disable specific tools by configuring the SDK client options.
• Extensibility: You can define custom agents, skills, and tools to extend agent functionality.

The Rust crate github-copilot-sdk is released using a unified workflow.

• Version Management: The rust/Cargo.toml uses 0.0.0-dev as a placeholder. The actual version is computed and injected by the publish.yml workflow at publish time.
• Tags: Releases are tagged using the rust/vX.Y.Z format.
• Release Notes: Notes are auto-generated from PR titles. Ensure PR titles are descriptive for changes affecting the Rust surface.
• Prereleases: To use a beta/prerelease version, users must specify the exact version in their Cargo.toml, as Cargo skips prereleases by default.

Copilot CLI Extensions function as separate Node.js child processes that communicate with the Copilot CLI (the parent process) using JSON-RPC over stdio.

Key Workflow:

1. Discovery: The CLI scans .github/extensions/ in your project or the user's copilot config directory for subdirectories containing an extension.mjs file.
2. Launch: The CLI forks the extension as a child process. The @github/copilot-sdk is automatically available via a module resolver; you do not need to install it manually.
3. Connection: The extension uses joinSession() to establish the JSON-RPC connection and attach to the current foreground session.
4. Registration: Tools and hooks defined in the session options are registered with the CLI and become available to the agent.
5. Lifecycle: Extensions reload on /clear or session replacement, and terminate when the CLI exits.

The SDK operates in a layered architecture:

1. Your Application interacts with the SDK.
2. github_copilot_sdk::Client manages the CLI process lifecycle (spawning, health-checking, and graceful shutdown).
3. github_copilot_sdk::Session manages the per-session event loop and handler dispatch.
4. Communication occurs via JSON-RPC 2.0 over stdio (using Content-Length framing, similar to LSP) or via TCP to the copilot --server process.

The Copilot SDK communicates with the CLI via a JSON-RPC protocol. Because of this, many interactive terminal-specific features (like TUI dialogs, slash commands, and visual rendering) are only available in the CLI and are not exposed to the SDK.

When building with the SDK, use the programmatic methods provided (e.g., session.rpc.plan.* instead of the /plan slash command) to achieve equivalent functionality.

The Copilot SDK follows a consistent pattern: your application interacts with the SDK, which then communicates with the Copilot CLI via JSON-RPC (using either stdio or TCP).

The CLI manages the following core responsibilities:

• JSON-RPC Server: Handles communication from the SDK.
• Authentication: Manages user identity.
• Session Manager: Handles session state.
• Model Provider: Interfaces with the underlying AI models.

When streaming: true is enabled on a session, the Copilot SDK emits real-time events. These are categorized into two types:

• Ephemeral events: Transient events (like deltas or progress updates) streamed in real time. They are not persisted to the session log and cannot be replayed when resuming a session.
• Persisted events: Events (like complete messages or tool results) that are saved to the session event log on disk and can be replayed when resuming a session.

Events can be linked using a parentId chain, where each event's parentId points to the previous event in the sequence.

You can use the Copilot SDK as an agent provider within the Microsoft Agent Framework (MAF) to build multi-agent workflows alongside other providers like Azure OpenAI or Anthropic.

Dedicated integration packages are available for .NET and Python. For TypeScript, Go, Java, and Rust, you should use the standard Copilot SDK directly, as its native APIs already support tool calling, streaming, and custom agents.