Copilot SDK for Java - Documentation

⚠️ Disclaimer: This is an unofficial, community-driven SDK and is not supported or endorsed by GitHub. Use at your own risk.

This guide covers common use cases for the Copilot SDK for Java. For complete API details, see the Javadoc.

Basic Usage
Handling Responses
Streaming Responses
Choosing a Model
Session Management

Basic Usage

Create a client, start a session, and send a message:

import com.github.copilot.sdk.*;
import com.github.copilot.sdk.json.*;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig().setModel("gpt-4.1")
    ).get();

    var response = session.sendAndWait("Explain Java records in one sentence").get();
    System.out.println(response.getData().getContent());

    session.close();
}

The client manages the connection to the Copilot CLI. Sessions are independent conversations that can run concurrently.

Handling Responses

Simple Request-Response

For straightforward interactions, use sendAndWait():

var response = session.sendAndWait("What is the capital of France?").get();
System.out.println(response.getData().getContent());

Event-Based Processing

For more control, subscribe to events and use send():

var done = new CompletableFuture<Void>();

session.on(event -> {
    if (event instanceof AssistantMessageEvent msg) {
        System.out.println("Response: " + msg.getData().getContent());
    } else if (event instanceof SessionErrorEvent err) {
        System.err.println("Error: " + err.getData().getMessage());
    } else if (event instanceof SessionIdleEvent) {
        done.complete(null);
    }
});

session.send("Tell me a joke").get();
done.get(); // Wait for completion

Key Event Types

Event	Description
`AssistantMessageEvent`	Complete assistant response
`AssistantMessageDeltaEvent`	Streaming chunk (when streaming enabled)
`SessionIdleEvent`	Session finished processing
`SessionErrorEvent`	An error occurred
`ToolExecutionStartEvent`	Tool invocation started
`ToolExecutionCompleteEvent`	Tool invocation completed

See the events package Javadoc for all event types.

Streaming Responses

Enable streaming to receive response chunks as they're generated:

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-4.1")
        .setStreaming(true)
).get();

var done = new CompletableFuture<Void>();

session.on(event -> {
    if (event instanceof AssistantMessageDeltaEvent delta) {
        // Print each chunk as it arrives
        System.out.print(delta.getData().getDeltaContent());
    } else if (event instanceof SessionIdleEvent) {
        System.out.println(); // Newline at end
        done.complete(null);
    }
});

session.send("Write a haiku about Java").get();
done.get();

Choosing a Model

List Available Models

Query available models before creating a session:

List<ModelInfo> models = client.listModels().get();

for (ModelInfo model : models) {
    System.out.printf("%s (%s)%n", model.getId(), model.getName());
}

Use a Specific Model

var session = client.createSession(
    new SessionConfig().setModel("claude-sonnet-4")
).get();

Session Management

Multiple Concurrent Sessions

var session1 = client.createSession(
    new SessionConfig().setModel("gpt-4.1")
).get();

var session2 = client.createSession(
    new SessionConfig().setModel("claude-sonnet-4")
).get();

// Send messages concurrently
var future1 = session1.sendAndWait("Summarize REST APIs");
var future2 = session2.sendAndWait("Summarize GraphQL");

System.out.println("GPT: " + future1.get().getData().getContent());
System.out.println("Claude: " + future2.get().getData().getContent());

Resume a Previous Session

// Get the last session ID
String lastSessionId = client.getLastSessionId().get();

// Or list all sessions
List<SessionMetadata> sessions = client.listSessions().get();

// Resume a session
var session = client.resumeSession(lastSessionId).get();

Clean Up Sessions

// Delete a specific session
client.deleteSession(sessionId).get();

Next Steps

📖 Advanced Usage - Tools, BYOK, MCP Servers, System Messages, Infinite Sessions
📖 MCP Servers - Integrate external tools via Model Context Protocol
📖 API Javadoc - Complete API reference