How to Use the GitHub Copilot SDK with Java: A Complete Integration Guide

The GitHub Copilot SDK for Java provides a typed, asynchronous API that launches a Copilot CLI server process via JSON-RPC, exposing high-level objects like CopilotClient and CopilotSession to embed AI assistants directly into Java applications.

The github/copilot-sdk repository delivers a native Java SDK that enables developers to integrate GitHub Copilot capabilities without external HTTP calls. The SDK manages a child CLI server process and exposes strongly-typed RPC namespaces, allowing you to create conversational sessions, stream responses, and access model metadata using standard Java patterns.

Architecture Overview

The SDK implements a three-layer architecture that abstracts process management, conversation state, and remote procedure calls.

Transport and Process Management

At the foundation, CopilotClient creates a CliServerManager that spawns or connects to a Copilot CLI server. According to java/src/main/java/com/github/copilot/CopilotClient.java, the client builds a Connection object owning the JSON-RPC client (ServerRpc) and the child process handle. This layer handles lifecycle methods including stop() for graceful shutdown and forceStop() for immediate termination.

Session Lifecycle Management

A CopilotSession represents a single conversation thread. As implemented in java/src/main/java/com/github/copilot/CopilotSession.java, you instantiate sessions via client.createSession(SessionConfig) or resume existing ones with client.resumeSession(). The session automatically patches configuration options through updateSessionOptionsForMode after creation, supporting tool filtering and skill enablement. You register event listeners for streaming events like AssistantMessageEvent and SessionUsageInfoEvent to handle real-time responses.

Typed RPC Facade

After calling client.start(), the method client.getRpc() returns a ServerRpc object exposing generated namespaces including models, tools, and account. These calls return standard CompletableFuture instances, enabling composable asynchronous workflows such as client.getRpc().models.list() for model discovery.

Installation and Requirements

The SDK requires Java 17 or higher as a baseline, with optimized virtual-thread support available on JDK 25 and above.

Add the dependency to your build configuration:

<!-- pom.xml -->
<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>1.0.0</version>
</dependency>

// build.gradle
implementation 'com.github:copilot-sdk-java:1.0.0'

For detailed environment setup, refer to java/docs/getting-started.md in the repository.

Implementing the Client Workflow

Initialize and Start the Client

Create a CopilotClient instance and establish the RPC channel. The start() method returns a CompletableFuture that completes when the CLI server is ready.

var client = new CopilotClient();
client.start().get();  // Blocks until connection established

Create and Configure a Session

Instantiate a session using SessionConfig to define permission handling and model selection. The java/src/main/java/com/github/copilot/CopilotClient.java implementation supports fluent configuration for security policies.

var session = client.createSession(
    new SessionConfig()
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setModel("claude-sonnet-4.5")
).get();

Register Event Listeners

Subscribe to event types to process streaming responses asynchronously. The SDK dispatches AssistantMessageEvent for content chunks and SessionUsageInfoEvent for token metrics.

session.on(AssistantMessageEvent.class, 
    ev -> System.out.println(ev.getData().content()));
    
session.on(SessionUsageInfoEvent.class,
    ev -> System.out.println("Tokens used: " + ev.getData().currentTokens()));

Send Prompts and Handle Responses

Submit user input via sendAndWait(), which accepts MessageOptions for prompt configuration. This method blocks until the conversation turn completes while still allowing event handlers to process streaming data.

session.sendAndWait(
    new MessageOptions().setPrompt("Explain the singleton pattern")
).get();

Graceful Shutdown

Always terminate the client to release resources and stop the child process. Use try-with-resources for automatic cleanup or invoke client.stop().get() explicitly.

client.stop().get();

Complete Working Example

This standalone implementation, derived from the Quick-Start section in java/README.md, demonstrates the full lifecycle including resource management:

import com.github.copilot.CopilotClient;
import com.github.copilot.generated.AssistantMessageEvent;
import com.github.copilot.generated.SessionUsageInfoEvent;
import com.github.copilot.rpc.MessageOptions;
import com.github.copilot.rpc.PermissionHandler;
import com.github.copilot.rpc.SessionConfig;

public class CopilotDemo {
    public static void main(String[] args) throws Exception {
        try (var client = new CopilotClient()) {
            client.start().get();

            var session = client.createSession(
                new SessionConfig()
                    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
                    .setModel("claude-sonnet-4.5"))
                .get();

            session.on(AssistantMessageEvent.class, 
                ev -> System.out.println(ev.getData().content()));
            session.on(SessionUsageInfoEvent.class,
                ev -> System.out.println("Tokens: " + ev.getData().currentTokens()));

            session.sendAndWait(
                new MessageOptions().setPrompt("Explain the singleton pattern")
            ).get();
        }
    }
}

Quick Testing with JBang

For rapid prototyping without build tools, the repository provides java/jbang-example.java. This single-file executable demonstrates event handling and prompt submission and can be run directly:

jbang https://github.com/github/copilot-sdk/blob/main/java/jbang-example.java

Accessing Server-Level APIs

Beyond conversations, access global capabilities like model enumeration through the RPC facade:

client.start().get();
var models = client.getRpc().models.list().get();
models.forEach(m -> System.out.println(m.getName() + " – " + m.getDescription()));

Summary

• The SDK architecture separates transport management (CopilotClient), conversation state (CopilotSession), and typed RPC access (ServerRpc).
• Core files include java/src/main/java/com/github/copilot/CopilotClient.java for entry points and java/src/main/java/com/github/copilot/CopilotSession.java for interaction logic.
• Java 17 is the minimum supported version, with enhanced performance on JDK 25+.
• All operations return CompletableFuture for flexible asynchronous or synchronous usage.
• Event-driven design supports real-time streaming of assistant responses and usage metrics.

Frequently Asked Questions

What Java version is required for the GitHub Copilot SDK?

The SDK requires Java 17 or higher as a baseline. For applications running on JDK 25 or above, the SDK automatically leverages virtual threads for improved concurrency performance.

How does the SDK communicate with the Copilot service?

The SDK launches a Copilot CLI server as a child process (or connects to an existing one via cliUrl) and establishes a JSON-RPC channel over STDIO or TCP. This architecture is implemented in java/src/main/java/com/github/copilot/CopilotClient.java and manages process lifecycle through Connection and CliServerManager objects.

Can I use the SDK without Maven or Gradle?

Yes. The repository includes java/jbang-example.java, a standalone executable script compatible with JBang. This approach requires no build configuration and runs with a single command, making it ideal for testing and demonstration purposes.

How do I handle long-running or streaming responses?

Register event listeners on the CopilotSession instance for AssistantMessageEvent.class to receive content chunks as they are generated. The sendAndWait() method returns a CompletableFuture that completes when the full response is finished, allowing you to combine streaming event handling with synchronous coordination points.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}