Copilot SDK for Java - Documentation

CopilotClient

new CopilotClient()
new CopilotClient(CopilotClientOptions options)

CopilotSession

Represents a single conversation session.

var subscription = session.on(evt -> {
    System.out.println("Event: " + evt.getType());
});

// Later...
subscription.close();

Manual Server Control

var client = new CopilotClient(
    new CopilotClientOptions().setAutoStart(false)
);

// Start manually
client.start().get();

// Use client...

// Stop manually
client.stop().get();

Tools

You can let the CLI call back into your process when the model needs capabilities you own:

var lookupTool = ToolDefinition.create(
    "lookup_issue",
    "Fetch issue details from our tracker",
    Map.of(
        "type", "object",
        "properties", Map.of(
            "id", Map.of("type", "string", "description", "Issue identifier")
        ),
        "required", List.of("id")
    ),
    invocation -> {
        String id = ((Map<String, Object>) invocation.getArguments()).get("id").toString();
        return CompletableFuture.completedFuture(fetchIssue(id));
    }
);

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-5")
        .setTools(List.of(lookupTool))
).get();

System Message Customization

Control the system prompt using SystemMessageConfig in session config:

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-5")
        .setSystemMessage(new SystemMessageConfig()
            .setMode(SystemMessageMode.APPEND)
            .setContent("""
                <workflow_rules>
                - Always check for security vulnerabilities
                - Suggest performance improvements when applicable
                </workflow_rules>
            """))
).get();

For full control (removes all guardrails), use REPLACE mode:

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-5")
        .setSystemMessage(new SystemMessageConfig()
            .setMode(SystemMessageMode.REPLACE)
            .setContent("You are a helpful assistant."))
).get();

Multiple Sessions

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

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

// Both sessions are independent
session1.send(new MessageOptions().setPrompt("Hello from session 1")).get();
session2.send(new MessageOptions().setPrompt("Hello from session 2")).get();

File Attachments

session.send(new MessageOptions()
    .setPrompt("Analyze this file")
    .setAttachments(List.of(
        new Attachment()
            .setType("file")
            .setPath("/path/to/file.java")
            .setDisplayName("My File")
    ))
).get();

Bring Your Own Key (BYOK)

Use a custom API provider:

var session = client.createSession(
    new SessionConfig()
        .setProvider(new ProviderConfig()
            .setType("openai")
            .setBaseUrl("https://api.openai.com/v1")
            .setApiKey("your-api-key"))
).get();

Permission Handling

Handle permission requests from the CLI:

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-5")
        .setOnPermissionRequest((request, invocation) -> {
            // Approve or deny the permission request
            var result = new PermissionRequestResult();
            result.setKind("user-approved");
            return CompletableFuture.completedFuture(result);
        })
).get();

Infinite Sessions

Infinite sessions enable automatic context management for long-running conversations. When enabled (default), the session automatically manages context window limits through background compaction and persists state to a workspace directory.

var infiniteConfig = new InfiniteSessionConfig()
    .setEnabled(true)
    .setBackgroundCompactionThreshold(0.80)  // Start compacting at 80% utilization
    .setBufferExhaustionThreshold(0.95);     // Block at 95% until compaction completes

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

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-5")
        .setInfiniteSessions(new InfiniteSessionConfig().setEnabled(true))
).get();

String workspacePath = session.getWorkspacePath();
if (workspacePath != null) {
    System.out.println("Session workspace: " + workspacePath);
    // Access checkpoints/, plan.md, files/ subdirectories
}

var session = client.createSession(
    new SessionConfig()
        .setModel("gpt-5")
        .setInfiniteSessions(new InfiniteSessionConfig().setEnabled(false))
).get();

// session.getWorkspacePath() will return null

MCP Servers

The Copilot SDK can integrate with MCP servers (Model Context Protocol) to extend the assistant's capabilities with external tools. MCP servers run as separate processes and expose tools that Copilot can invoke during conversations.

📖 Full MCP documentation → - Learn about local vs remote servers, all configuration options, and troubleshooting.

Quick example:

Map<String, Object> filesystemServer = new HashMap<>();
filesystemServer.put("type", "local");
filesystemServer.put("command", "npx");
filesystemServer.put("args", List.of("-y", "@modelcontextprotocol/server-filesystem", "/tmp"));
filesystemServer.put("tools", List.of("*"));

var session = client.createSession(
    new SessionConfig()
        .setMcpServers(Map.of("filesystem", filesystemServer))
).get();