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