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

> Integrate GitHub Copilot SDK with Java. This guide shows how to embed AI assistants using the typed, asynchronous API and high-level objects like CopilotClient and CopilotSession.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: how-to-guide
- Published: 2026-06-06

---

**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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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:

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

```

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

```

For detailed environment setup, refer to [`java/docs/getting-started.md`](https://github.com/github/copilot-sdk/blob/main/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.

```java
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`](https://github.com/github/copilot-sdk/blob/main/java/src/main/java/com/github/copilot/CopilotClient.java) implementation supports fluent configuration for security policies.

```java
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.

```java
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.

```java
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.

```java
client.stop().get();

```

## Complete Working Example

This standalone implementation, derived from the Quick-Start section in [`java/README.md`](https://github.com/github/copilot-sdk/blob/main/java/README.md), demonstrates the full lifecycle including resource management:

```java
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`](https://github.com/github/copilot-sdk/blob/main/java/jbang-example.java). This single-file executable demonstrates event handling and prompt submission and can be run directly:

```bash
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:

```java
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`](https://github.com/github/copilot-sdk/blob/main/java/src/main/java/com/github/copilot/CopilotClient.java) for entry points and [`java/src/main/java/com/github/copilot/CopilotSession.java`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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.