GitHub Copilot SDK (Rust)

github-copilot-sdk is the official Rust client for the GitHub Copilot CLI, giving Rust applications programmatic control over the same production-tested agent runtime that powers Copilot CLI. Instead of building your own planning and tool-orchestration loop, applications spawn or connect to a copilot --server process and drive it over JSON-RPC: creating sessions, sending prompts, streaming assistant events, and responding to permission, elicitation, and user-input callbacks through focused handler traits.

The crate ships a fully-typed RPC namespace generated directly from the Copilot CLI’s protocol schema, so new server methods are available immediately without waiting on hand-written wrappers, alongside ergonomic helpers for the common paths — sending messages, managing sessions, registering client-side tools, and intercepting tool calls with lifecycle hooks. Optional features bundle the Copilot CLI binary at build time or host it in-process via FFI, and BYOK support lets applications supply their own LLM provider keys instead of requiring a GitHub Copilot subscription.

What You Get

• A Client/Session API that manages the Copilot CLI process lifecycle (spawn, health-check, graceful shutdown) and exposes create/resume/send/subscribe operations.
• A fully-typed JSON-RPC namespace (client.rpc() / session.rpc()) generated from the Copilot CLI’s protocol schema, covering every wire method including ones without a hand-written helper.
• Five focused handler traits (permission, elicitation, user-input, exit-plan-mode, auto-mode-switch) so you implement only the callbacks your integration needs.
• Session hooks (PreToolUse, PostToolUse, SessionStart/SessionEnd, etc.) and system-message transforms for intercepting and customizing agent behavior.
• Client-side tool registration via named ToolHandler types with schemars-generated JSON Schema, plus a define_tool shortcut for trivial tools.
• Optional bundled-CLI and in-process FFI transports so consumers don’t have to install or manage the Copilot CLI binary separately.

Common Use Cases

• Embedding an AI coding-agent chat experience directly into a Rust IDE plugin or desktop application.
• Building a custom automation pipeline that drives Copilot’s planning and tool-use loop from CI or a backend service.
• Wrapping Copilot’s agent runtime behind an internal API so multiple teams can consume it without each reimplementing the JSON-RPC protocol.
• Enforcing organization-specific permission policies on tool calls via a custom PermissionHandler before the agent can execute file edits or shell commands.

Under The Hood

Architecture The Rust SDK layers a Client that owns the CLI process lifecycle (spawn, health-check, graceful shutdown, with bundled-binary extraction) over a Session that runs a per-session event loop dispatching CLI callbacks to five focused handler traits installed via SessionConfig. A SessionRouter demultiplexes JSON-RPC notifications and requests by session ID into per-session channels, decoupling the shared JSON-RPC transport (Content-Length framing similar to LSP) from session-specific handler dispatch. A generated protocol-types module is deliberately crate-private, exposed only through rpc and session_events facade modules, so downstream code never binds to generated internals directly and new RPCs land automatically without breaking the public API. Optional features (bundled CLI, in-process FFI hosting a runtime cdylib, schemars-based tool derivation) are cleanly feature-gated, and cross-cutting concerns — hooks, system-message transforms, canvas support, a virtualizable session filesystem — are each isolated into their own dispatch modules rather than bolted onto the session type directly.

Tech Stack Rust edition 2024 with an MSRV of 1.94.0. The async runtime is tokio with async-trait for trait-object handler dispatch and tokio-stream/tokio-util for event streaming. JSON-RPC payloads use serde/serde_json with indexmap for ordered maps; schemars optionally generates JSON Schema for typed tool parameters. The LLM-inference callback transport uses reqwest (HTTP/2) and tokio-tungstenite for WebSocket forwarding, with http/bytes/futures-util handling the chunked protocol. The bundled-CLI feature downloads and verifies the Copilot CLI binary at build time via a build script using ureq, native-tls, flate2/tar, and sha2. parking_lot supplies faster mutexes than the standard library, and the crate ships as a library consumable via cargo add github-copilot-sdk rather than a framework or application server.

Code Quality Testing is extensive and multi-layered: one integration file alone defines well over a hundred test functions, with additional suites covering API types, JSON-RPC framing, CLI resolution, protocol-version negotiation, and a dedicated end-to-end test directory; two integration tests require a test-support feature specifically because cfg(test) isn’t set when Cargo compiles integration tests, showing deliberate attention to test-only surface area. Error handling is fully typed rather than stringly-typed, with a shared internal representation reused across every crate error type and non-exhaustive kind enums that carry structured context. The crate denies missing documentation and broken intra-doc links at compile time, and CI runs dedicated test, lint, and generated-code-freshness workflows for the Rust SDK alongside its sibling language SDKs.

API Design The public API favors ergonomic convenience wrapped tightly around the fully-typed generated RPC namespace: simple string sends work directly, while the raw RPC namespace exposes every wire method with strongly-typed request/response structs the moment the protocol schema adds them. Five single-method handler traits let consumers opt into only the callbacks they need, with CLI wire flags derived automatically from which traits are installed, and a builder-style config chain composes handlers, hooks, transforms, and tools onto one object. Tool registration favors named types over closures for stack-trace and IDE navigability, with a shorthand helper for trivial one-off tools. Startup exposes per-phase timing diagnostics without log-scraping, and CLI-resolution order is documented precisely rather than left as implicit auto-detection.