Package com.github.copilot.sdk

Class CopilotClient

java.lang.Object
com.github.copilot.sdk.CopilotClient
All Implemented Interfaces:
AutoCloseable
public final class CopilotClient extends Object implements AutoCloseable
Provides a client for interacting with the Copilot CLI server.

The CopilotClient manages the connection to the Copilot CLI server and provides methods to create and manage conversation sessions. It can either spawn a CLI server process or connect to an existing server.

Example usage: 


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

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

 	session.on(AssistantMessageEvent.class, msg -> {
 		System.out.println(msg.getData().content());
 	});

 	session.send(new MessageOptions().setPrompt("Hello!")).get();
 }
Since:
1.0.0

  • Field Details

    • AUTOCLOSEABLE_TIMEOUT_SECONDS

      public static final int AUTOCLOSEABLE_TIMEOUT_SECONDS
      Timeout, in seconds, used by close() when waiting for graceful shutdown via stop().
      See Also:

  • Constructor Details

    • CopilotClient

      public CopilotClient()
      Creates a new CopilotClient with default options.

    • CopilotClient

      public CopilotClient(CopilotClientOptions options)
      Creates a new CopilotClient with the specified options.
      Parameters:
      options - Options for creating the client
      Throws:
      IllegalArgumentException - if mutually exclusive options are provided

  • Method Details

    • start

      public CompletableFuture<Void> start()
      Starts the Copilot client and connects to the server.
      Returns:
      A future that completes when the connection is established

    • stop

      public CompletableFuture<Void> stop()
      Stops the client and closes all sessions.
      Returns:
      A future that completes when the client is stopped

    • forceStop

      public CompletableFuture<Void> forceStop()
      Forces an immediate stop of the client without graceful cleanup.
      Returns:
      A future that completes when the client is stopped

    • createSession

      public CompletableFuture<CopilotSession> createSession(SessionConfig config)
      Creates a new Copilot session with the specified configuration.

      The session maintains conversation state and can be used to send messages and receive responses. Remember to close the session when done.

      Parameters:
      config - configuration for the session (model, tools, etc.)
      Returns:
      a future that resolves with the created CopilotSession
      See Also:

    • createSession

      public CompletableFuture<CopilotSession> createSession()
      Creates a new Copilot session with default configuration.
      Returns:
      a future that resolves with the created CopilotSession
      See Also:

    • resumeSession

      public CompletableFuture<CopilotSession> resumeSession(String sessionId, ResumeSessionConfig config)
      Resumes an existing Copilot session.

      This restores a previously saved session, allowing you to continue a conversation. The session's history is preserved.

      Parameters:
      sessionId - the ID of the session to resume
      config - configuration for the resumed session
      Returns:
      a future that resolves with the resumed CopilotSession
      See Also:

    • resumeSession

      public CompletableFuture<CopilotSession> resumeSession(String sessionId)
      Resumes an existing session with default configuration.
      Parameters:
      sessionId - the ID of the session to resume
      Returns:
      a future that resolves with the resumed CopilotSession
      See Also:

    • getState

      public ConnectionState getState()
      Gets the current connection state.
      Returns:
      the current connection state
      See Also:

    • ping

      public CompletableFuture<PingResponse> ping(String message)
      Pings the server to check connectivity.

      This can be used to verify that the server is responsive and to check the protocol version.

      Parameters:
      message - an optional message to echo back
      Returns:
      a future that resolves with the ping response
      See Also:

    • getStatus

      public CompletableFuture<GetStatusResponse> getStatus()
      Gets CLI status including version and protocol information.
      Returns:
      a future that resolves with the status response containing version and protocol version
      See Also:

    • getAuthStatus

      public CompletableFuture<GetAuthStatusResponse> getAuthStatus()
      Gets current authentication status.
      Returns:
      a future that resolves with the authentication status
      See Also:

    • listModels

      public CompletableFuture<List<ModelInfo>> listModels()
      Lists available models with their metadata.

      Results are cached after the first successful call to avoid rate limiting. The cache is cleared when the client disconnects.

      Returns:
      a future that resolves with a list of available models
      See Also:

    • getLastSessionId

      public CompletableFuture<String> getLastSessionId()
      Gets the ID of the most recently used session.

      This is useful for resuming the last conversation without needing to list all sessions.

      Returns:
      a future that resolves with the last session ID, or null if no sessions exist
      See Also:

    • deleteSession

      public CompletableFuture<Void> deleteSession(String sessionId)
      Deletes a session by ID.

      This permanently removes the session and its conversation history.

      Parameters:
      sessionId - the ID of the session to delete
      Returns:
      a future that completes when the session is deleted
      Throws:
      RuntimeException - if the deletion fails

    • listSessions

      public CompletableFuture<List<SessionMetadata>> listSessions()
      Lists all available sessions.

      Returns metadata about all sessions that can be resumed, including their IDs, start times, and summaries.

      Returns:
      a future that resolves with a list of session metadata
      See Also:

    • listSessions

      public CompletableFuture<List<SessionMetadata>> listSessions(SessionListFilter filter)
      Lists all available sessions with optional filtering.

      Returns metadata about all sessions that can be resumed, including their IDs, start times, summaries, and context information. Use the filter parameter to narrow down sessions by working directory, git repository, or branch.

      Example Usage

      
 // List all sessions
 var allSessions = client.listSessions().get();

 // Filter by repository
 var filter = new SessionListFilter().setRepository("owner/repo");
 var repoSessions = client.listSessions(filter).get();
      Parameters:
      filter - optional filter to narrow down sessions by context fields, or null to list all sessions
      Returns:
      a future that resolves with a list of session metadata
      See Also:

    • getForegroundSessionId

      public CompletableFuture<String> getForegroundSessionId()
      Gets the ID of the session currently displayed in the TUI.

      This is only available when connecting to a server running in TUI+server mode (--ui-server).

      Returns:
      a future that resolves with the session ID, or null if no foreground session is set

    • setForegroundSessionId

      public CompletableFuture<Void> setForegroundSessionId(String sessionId)
      Requests the TUI to switch to displaying the specified session.

      This is only available when connecting to a server running in TUI+server mode (--ui-server).

      Parameters:
      sessionId - the ID of the session to display in the TUI
      Returns:
      a future that completes when the operation is done
      Throws:
      RuntimeException - if the operation fails

    • onLifecycle

      public AutoCloseable onLifecycle(SessionLifecycleHandler handler)
      Subscribes to all session lifecycle events.

      Lifecycle events are emitted when sessions are created, deleted, updated, or change foreground/background state (in TUI+server mode).

      Parameters:
      handler - a callback that receives lifecycle events
      Returns:
      an AutoCloseable that, when closed, unsubscribes the handler

    • onLifecycle

      public AutoCloseable onLifecycle(String eventType, SessionLifecycleHandler handler)
      Subscribes to a specific session lifecycle event type.
      Parameters:
      eventType - the event type to listen for (use SessionLifecycleEventTypes constants)
      handler - a callback that receives events of the specified type
      Returns:
      an AutoCloseable that, when closed, unsubscribes the handler

    • close

      public void close()
      Closes this client using graceful shutdown semantics.

      This method is intended for try-with-resources usage and blocks while waiting for stop() to complete, up to AUTOCLOSEABLE_TIMEOUT_SECONDS seconds. If shutdown fails or times out, the error is logged at Level.FINE and the method returns.

      This method is idempotent.

      Specified by:
      close in interface AutoCloseable
      See Also: