GitHub Copilot SDK Java Instructions

Core Principles

- The SDK is in public preview and may have breaking changes

- Requires Java 17 or later for baseline SDK usage. Some examples use newer JDK features and therefore require JDK 21 or later (for example, virtual threads via `Executors.newVirtualThreadPerTaskExecutor()` and `switch` pattern matching). **Java 25 or later highly recommended**.

- Requires GitHub Copilot CLI installed and in PATH

- Uses `CompletableFuture` for all async operations

- Implements `AutoCloseable` for resource cleanup (try-with-resources)

- Getters on configuration classes return `Optional<T>` (or `OptionalInt`/`OptionalDouble`) to distinguish "not set" from explicit values; setters accept raw types and return `this` for chaining. Use the `clear` methods to unset values if needed.

Installation

Maven

<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>${copilot-sdk-java.version}</version>
</dependency>

Gradle

implementation "com.github:copilot-sdk-java:${copilotSdkJavaVersion}"

Client Initialization

Basic Client Setup

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

Virtual Threads (JDK 25+)

Virtual threads were introduced in JDK 21, but significant performance bugs were not fixed until JDK 25, making JDK 25 the minimum recommended version for production use of virtual threads. On JDK 25+, use a virtual-thread executor for significantly better scalability. The SDK's async operations will run on virtual threads instead of the default `ForkJoinPool`:

var options = new CopilotClientOptions()
    .setExecutor(Executors.newVirtualThreadPerTaskExecutor());

try (var client = new CopilotClient(options)) {
    client.start().get();
    // Use client...
}

Client Configuration Options

When creating a CopilotClient, use `CopilotClientOptions`:

- `cliPath` - Path to CLI executable (default: "copilot" from PATH)

- `cliArgs` - Extra arguments prepended before SDK-managed flags

- `cliUrl` - URL of existing CLI server (e.g., "localhost:8080"). When provided, client won't spawn a process

- `port` - Server port (default: 0 for random, only when `useStdio` is false)

- `useStdio` - Use stdio transport instead of TCP (default: true)

- `logLevel` - Log level: "error", "warn", "info", "debug", "trace" (default: "info")

- `autoStart` - Auto-start server on first request (default: true)

- `autoRestart` - Auto-restart on crash (default: true)

- `cwd` - Working directory for the CLI process

- `environment` - Environment variables for the CLI process

- `gitHubToken` - GitHub token for authentication

- `useLoggedInUser` - Use logged-in `gh` CLI auth (default: true unless token provided)

- `onListModels` - Custom model list handler for BYOK scenarios

- `remote` - Enable Mission Control / cloud session integration (default: false)

- `telemetry` - `TelemetryConfig` for OpenTelemetry export (since 1.2.0)

- `sessionIdleTimeoutSeconds` - Idle timeout before session auto-closes (since 1.3.0)

- `executor` - Custom `Executor` for async operations (default: ForkJoinPool)

- `tcpConnectionToken` - Security token for TCP transport authentication

var options = new CopilotClientOptions()
    .setCliPath("/path/to/copilot")
    .setLogLevel("debug")
    .setAutoStart(true)
    .setAutoRestart(true)
    .setGitHubToken(System.getenv("GITHUB_TOKEN"));

try (var client = new CopilotClient(options)) {
    client.start().get();
    // Use client...
}

Manual Server Control

For explicit control:

var client = new CopilotClient(new CopilotClientOptions().setAutoStart(false));
client.start().get();
// Use client...
client.stop().get();

Use `forceStop()` when `stop()` takes too long.

Session Management

Creating Sessions

Use `SessionConfig` for configuration. The permission handler is **required**:

var session = client.createSession(new SessionConfig()
    .setM