Copilot SDK for Java

Latest release

Overview

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

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
• GitHub Copilot CLI 0.0.409 or later installed and in PATH (or provide custom cliPath)

Maven

<dependency>
    <groupId>io.github.copilot-community-sdk</groupId>
    <artifactId>copilot-sdk</artifactId>
    <version>1.0.8</version>
</dependency>

Gradle

implementation 'io.github.copilot-community-sdk:copilot-sdk:1.0.8'

Quick Start

import com.github.copilot.sdk.*;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;
import java.util.concurrent.CompletableFuture;

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

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

            // Handle assistant message events
            session.on(AssistantMessageEvent.class, msg -> {
                System.out.println(msg.getData().getContent());
            });

            // 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: " + (int) data.getCurrentTokens());
                System.out.println("Token limit: " + (int) data.getTokenLimit());
                System.out.println("Messages count: " + (int) data.getMessagesLength());
            });

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

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/copilot-community-sdk/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

Projects Using This SDK

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

Want to add your project? Open a PR!

CI/CD Workflows

This project uses several GitHub Actions workflows for building, testing, releasing, and syncing with the upstream 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 Upstream Merge and Sync

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

Weekly automated sync — A scheduled GitHub Actions workflow runs every Monday at 5 AM ET. It checks for new upstream commits since the last merge (tracked in .lastmerge), and if changes are found, creates an issue labeled upstream-sync and assigns it to the GitHub Copilot coding agent. Any previously open upstream-sync issues are automatically closed.

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

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

Automated Test Coverage Improvement

The repository includes an Agentic Workflow that automatically identifies untested code and creates comprehensive tests to increase coverage. The workflow is triggered manually:

To run the workflow:

1. Navigate to the repository on GitHub
2. Go to Actions → Increase Test Coverage workflow
3. Click "Run workflow"
4. Optionally specify:
   • target_package — Focus on a specific package (e.g., com.github.copilot.sdk.json)
   • min_coverage_threshold — Target coverage percentage (default: 80%)

What it does:

• Analyzes current test coverage using JaCoCo
• Identifies methods, branches, and edge cases lacking tests
• Creates high-quality tests following repository patterns
• Groups related tests logically
• Creates a PR for human review with coverage metrics

The workflow follows all repository conventions (Spotless formatting, existing test patterns, E2E test infrastructure) and ensures no production code is modified unnecessarily.

Development Setup

# Clone the repository
git clone https://github.com/copilot-community-sdk/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.

License

MIT — see LICENSE for details.

Star History

⭐ Drop a star if you find this useful!