GitHub Copilot SDK for Java

May 16, 2026 · View on GitHub

Background

ℹ️ Public Preview: This SDK tracks the GitHub Copilot SDKs for .NET and Node.js. While in public preview, minor breaking changes may still occur between releases.

Java SDK for programmatic control of GitHub Copilot CLI, enabling you to build AI-powered applications and agentic workflows.

Installation

Requirements

Java 17 or later. JDK 25 recommended. Selecting JDK 25 enables the use of virtual threads, as shown in the Quick Start.
GitHub Copilot CLI 1.0.17 or later installed and in PATH (or provide custom cliPath)

Maven

<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>1.0.0-beta-java.4</version>
</dependency>

Snapshot Builds

Snapshot builds of the next development version are published to Maven Central Snapshots. To use them, add the repository and update the dependency version in your pom.xml:

<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>1.0.0-beta-java.5-SNAPSHOT</version>
</dependency>

Gradle

implementation 'com.github:copilot-sdk-java:1.0.0-beta-java.4'

Quick Start

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.generated.AssistantMessageEvent;
import com.github.copilot.sdk.generated.SessionUsageInfoEvent;
import com.github.copilot.sdk.json.CopilotClientOptions;
import com.github.copilot.sdk.json.MessageOptions;
import com.github.copilot.sdk.json.PermissionHandler;
import com.github.copilot.sdk.json.SessionConfig;

import java.util.concurrent.Executors;

public class CopilotSDK {
    public static void main(String[] args) throws Exception {
        var lastMessage = new String[]{null};

        // Create and start client
        try (var client = new CopilotClient()) {  // JDK 25+: comment out this line
        // JDK 25+: uncomment the following 3 lines for virtual thread support
        // var options = new CopilotClientOptions()
        //     .setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        // try (var client = new CopilotClient(options)) {
            client.start().get();

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


            // Handle assistant message events
            session.on(AssistantMessageEvent.class, msg -> {
                lastMessage[0] = msg.getData().content();
                System.out.println(lastMessage[0]);
            });

            // Handle session usage info events
            session.on(SessionUsageInfoEvent.class, usage -> {
                var data = usage.getData();
                System.out.println("\n--- Usage Metrics ---");
                System.out.println("Current tokens: " + data.currentTokens().intValue());
                System.out.println("Token limit: " + data.tokenLimit().intValue());
                System.out.println("Messages count: " + data.messagesLength().intValue());
            });

            // Send a message
            var completable = session.sendAndWait(new MessageOptions().setPrompt("What is 2+2?"));
            // and wait for completion
            completable.get();
        }

        boolean success = lastMessage[0] != null && lastMessage[0].contains("4");
        System.exit(success ? 0 : -1);
    }
}

Try it with JBang

You can run the SDK without setting up a full Java project, by using JBang.

See the full source of jbang-example.java for a complete example with more features like session idle handling and usage info events.

Or run it directly from the repository:

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

Documentation

📚 Full Documentation — Complete API reference, advanced usage examples, and guides.

Quick Links

Getting Started
Javadoc API Reference
MCP Servers Integration
Cookbook — Practical recipes for common use cases

Project	Description
JMeter Copilot Plugin	JMeter plugin for AI-assisted load testing

CI/CD Workflows

This project uses several GitHub Actions workflows for building, testing, releasing, and syncing with the reference implementation SDK.

See WORKFLOWS.md for a full overview and details on each workflow.

Contributing

Contributions are welcome! Please see the Contributing Guide for details.

Agentic Reference Implementation Merge and Sync

This SDK tracks the official Copilot SDK (.NET reference implementation) and ports changes to Java. The reference implementation merge process is automated with AI assistance:

Automated sync — A scheduled GitHub Actions workflow runs on the schedule specified in that file. It checks for new reference implementation commits since the last merge (tracked in .lastmerge), and if changes are found, creates an issue labeled reference-impl-sync and assigns it to the GitHub Copilot coding agent. Any previously open reference-impl-sync issues are automatically closed. The sync also updates the @github/copilot version in both pom.xml and scripts/codegen/package.json to keep schemas and test CLI in lockstep.

Reusable prompt — The merge workflow is defined in agentic-merge-reference-impl.prompt.md. It can be triggered manually from:

VS Code Copilot Chat — type /agentic-merge-reference-impl
GitHub Copilot CLI — use copilot CLI with the same skill reference

Development Setup

# Clone the repository
git clone https://github.com/github/copilot-sdk-java.git
cd copilot-sdk-java

# Enable git hooks for code formatting
git config core.hooksPath .githooks

# Build and test
mvn clean verify

The tests require the official copilot-sdk test harness, which is automatically cloned during build.

Initially developed with Copilot and Bruno Borges.

Star History

⭐ Drop a star if you find this useful!

GitHub Copilot SDK for Java

Latest release