Class CopilotClientOptions

java.lang.Object
com.github.copilot.rpc.CopilotClientOptions
public class CopilotClientOptions extends Object
Configuration options for creating a CopilotClient.

This class provides a fluent API for configuring how the client connects to and manages the Copilot CLI server. All setter methods return this for method chaining.

Example Usage

var options = new CopilotClientOptions().setCliPath("/usr/local/bin/copilot").setLogLevel("debug")
		.setAutoStart(true);

var client = new CopilotClient(options);
Since:
1.0.0
See Also:

  • Constructor Details

    • CopilotClientOptions

      public CopilotClientOptions()

  • Method Details

    • isAutoRestart

      @Deprecated public boolean isAutoRestart()
      Deprecated.
      This option has no effect and will be removed in a future release.
      Returns whether the client should automatically restart the server on crash.
      Returns:
      the auto-restart flag value (no longer has any effect)

    • setAutoRestart

      @Deprecated public CopilotClientOptions setAutoRestart(boolean autoRestart)
      Deprecated.
      This option has no effect and will be removed in a future release.
      Sets whether the client should automatically restart the CLI server if it crashes unexpectedly.
      Parameters:
      autoRestart - ignored — this option no longer has any effect
      Returns:
      this options instance for method chaining

    • isAutoStart

      public boolean isAutoStart()
      Returns whether the client should automatically start the server.
      Returns:
      true to auto-start (default), false for manual start

    • setAutoStart

      public CopilotClientOptions setAutoStart(boolean autoStart)
      Sets whether the client should automatically start the CLI server when the first request is made.
      Parameters:
      autoStart - true to auto-start, false for manual start
      Returns:
      this options instance for method chaining

    • getBuiltinPluginDirectories

      public List<Path> getBuiltinPluginDirectories()
      Gets the trusted plugin directories bundled by the host.
      Returns:
      a copy of the configured absolute paths, or null

    • setBuiltinPluginDirectories

      public CopilotClientOptions setBuiltinPluginDirectories(List<Path> paths)
      Sets trusted plugin directories bundled by the host. Every path must be absolute. When non-empty, the complete set is registered during startup before sessions can be created.
      Parameters:
      paths - absolute plugin directory paths, or null/empty to disable
      Returns:
      this options instance for method chaining

    • getExtensionLaunchProvider

      @CopilotExperimental public ExtensionLaunchProvider getExtensionLaunchProvider()
      Gets the connection-level extension launch profile provider.
      Returns:
      the provider, or null if not set

    • setExtensionLaunchProvider

      @CopilotExperimental public CopilotClientOptions setExtensionLaunchProvider(ExtensionLaunchProvider extensionLaunchProvider)
      Sets the connection-level extension launch profile provider.

      When provided, the client registers the provider during startup before any session can be created.

      Parameters:
      extensionLaunchProvider - the provider (must not be null)
      Returns:
      this options instance for method chaining

    • getInstallationConfirmationHandler

      @CopilotExperimental public InstallationConfirmationHandler getInstallationConfirmationHandler()
      Gets the connection-level installation confirmation handler.
      Returns:
      the handler, or null if not set

    • setInstallationConfirmationHandler

      @CopilotExperimental public CopilotClientOptions setInstallationConfirmationHandler(InstallationConfirmationHandler installationConfirmationHandler)
      Sets the connection-level installation confirmation handler.

      When provided, the client installs the installations.confirm reverse-RPC handler. This does not enable installation capabilities or call a runtime registration RPC.

      Parameters:
      installationConfirmationHandler - the handler (must not be null)
      Returns:
      this options instance for method chaining

    • getCliArgs

      public String[] getCliArgs()
      Gets the extra CLI arguments.

      Returns a shallow copy of the internal array, or null if no arguments have been set.

      Returns:
      a copy of the extra arguments, or null

    • setCliArgs

      public CopilotClientOptions setCliArgs(String[] cliArgs)
      Sets extra arguments to pass to the CLI process.

      These arguments are prepended before SDK-managed flags. A shallow copy of the provided array is stored. If null or empty, the existing arguments are cleared.

      Parameters:
      cliArgs - the extra arguments to pass, or null/empty to clear
      Returns:
      this options instance for method chaining

    • getCliPath

      public String getCliPath()
      Gets the path to an explicitly configured Copilot executable.
      Returns:
      the executable path, or null to use the bundled runtime wrapper

    • setCliPath

      public CopilotClientOptions setCliPath(String cliPath)
      Sets the path to the Copilot CLI or runtime wrapper executable.
      Parameters:
      cliPath - the path to the executable
      Returns:
      this options instance for method chaining

    • getCliUrl

      public String getCliUrl()
      Gets the URL of an existing CLI server to connect to.
      Returns:
      the CLI server URL, or null to spawn a new process

    • setCliUrl

      public CopilotClientOptions setCliUrl(String cliUrl)
      Sets the URL of an existing CLI server to connect to.

      When provided, the client will not spawn a CLI process but will connect to the specified URL instead. Format: "host:port" or "http://host:port".

      Note: This is mutually exclusive with setUseStdio(boolean) and setCliPath(String).

      Parameters:
      cliUrl - the CLI server URL to connect to (must not be null or empty)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if cliUrl is null or empty

    • getConnection

      @CopilotExperimental public RuntimeConnection getConnection()
      Gets the connection that selects how the client reaches the Copilot runtime.
      Returns:
      the connection, or null to infer the transport from isUseStdio(), getCliUrl() and getCliPath()

    • setConnection

      @CopilotExperimental public CopilotClientOptions setConnection(RuntimeConnection connection)
      Sets the connection that selects how the client reaches the Copilot runtime.

      When set, the connection takes precedence over the transport-selecting options setUseStdio(boolean), setCliUrl(String), setCliPath(String), setPort(int) and setTcpConnectionToken(String); combining a connection with conflicting values for any of those options makes the client constructor throw IllegalArgumentException. Values that match what the connection implies are accepted, so the same options instance can be reused across multiple client constructions.

      Parameters:
      connection - the connection, or null to infer the transport from the individual transport options
      Returns:
      this options instance for method chaining

    • getCopilotHome

      public String getCopilotHome()
      Gets the base directory for Copilot data (session state, config, etc.).
      Returns:
      the Copilot home directory path, or null to use the CLI default (~/.copilot)

    • setCopilotHome

      public CopilotClientOptions setCopilotHome(String copilotHome)
      Sets the base directory for Copilot data (session state, config, etc.).

      Sets the COPILOT_HOME environment variable on the spawned CLI process. When null, the COPILOT_HOME env var is not set on the spawned process, so the CLI falls back to its default (~/.copilot).

      This option is only used when the SDK spawns the CLI process; it is ignored when connecting to an external server via setCliUrl(String).

      Parameters:
      copilotHome - the Copilot home directory path, or null to use the CLI default
      Returns:
      this options instance for method chaining

    • getCwd

      public String getCwd()
      Gets the working directory for the CLI process.
      Returns:
      the working directory path

    • setCwd

      public CopilotClientOptions setCwd(String cwd)
      Sets the working directory for the CLI process.
      Parameters:
      cwd - the working directory path, or null to clear
      Returns:
      this options instance for method chaining

    • getEnvironment

      public Map<String,String> getEnvironment()
      Gets the environment variables for the CLI process.

      Returns a shallow copy of the internal map, or null if no environment has been set.

      Returns:
      a copy of the environment variables map, or null

    • setEnvironment

      public CopilotClientOptions setEnvironment(Map<String,String> environment)
      Sets environment variables to pass to the CLI process.

      When set, these environment variables replace the inherited environment. A shallow copy of the provided map is stored. If null or empty, the existing environment is cleared.

      Parameters:
      environment - the environment variables map, or null/empty to clear
      Returns:
      this options instance for method chaining

    • getExecutor

      public Executor getExecutor()
      Gets the executor used for internal asynchronous operations.

      Returns null if no executor has been explicitly set, indicating that the SDK should use its default executor strategy.

      Returns:
      the executor, or null if using SDK defaults

    • setExecutor

      public CopilotClientOptions setExecutor(Executor executor)
      Sets the executor used for internal asynchronous operations.

      When provided, the SDK uses this executor for all internal CompletableFuture combinators. This allows callers to isolate SDK work onto a dedicated thread pool or integrate with container-managed threading.

      The SDK will not shut down a user-provided executor. If you pass a custom ExecutorService, you remain responsible for shutting it down.

      If not set (or set to null), the SDK uses its default executor: virtual threads on JDK 25+, ForkJoinPool.commonPool() on older JDKs.

      Parameters:
      executor - the executor to use, or null for SDK defaults
      Returns:
      this options instance for fluent chaining

    • getGitHubToken

      public String getGitHubToken()
      Gets the GitHub token for authentication.
      Returns:
      the GitHub token, or null to use other authentication methods

    • setGitHubToken

      public CopilotClientOptions setGitHubToken(String gitHubToken)
      Sets the GitHub token to use for authentication.

      When provided, the token is passed to the CLI server via environment variable. This takes priority over other authentication methods.

      Parameters:
      gitHubToken - the GitHub token (must not be null or empty)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if gitHubToken is null or empty

    • getGithubToken

      @Deprecated public String getGithubToken()
      Deprecated.
      Use getGitHubToken() instead.
      Gets the GitHub token for authentication.
      Returns:
      the GitHub token, or null to use other authentication methods

    • setGithubToken

      @Deprecated public CopilotClientOptions setGithubToken(String githubToken)
      Deprecated.
      Use setGitHubToken(String) instead.
      Sets the GitHub token to use for authentication.
      Parameters:
      githubToken - the GitHub token
      Returns:
      this options instance for method chaining

    • getLogLevel

      public String getLogLevel()
      Gets the log level for the CLI process.
      Returns:
      the log level (default: "info")

    • setLogLevel

      public CopilotClientOptions setLogLevel(String logLevel)
      Sets the log level for the CLI process.

      Valid levels include: "error", "warn", "info", "debug", "trace".

      Parameters:
      logLevel - the log level (must not be null or empty)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if logLevel is null or empty

    • getMode

      public CopilotClientMode getMode()
      Gets the SDK defaulting strategy.
      Returns:
      the client mode (never null)
      Since:
      1.3.0

    • setMode

      public CopilotClientOptions setMode(CopilotClientMode mode)
      Sets the SDK defaulting strategy.

      When set to CopilotClientMode.EMPTY, the SDK validates that the app has supplied the required configuration (e.g. setCopilotHome(String)) and translates session creation requests into runtime options that flip tool filter precedence to excluded-wins so exclusions are expressible.

      Parameters:
      mode - the client mode
      Returns:
      this options instance for method chaining
      Since:
      1.3.0

    • getOnListModels

      public Supplier<CompletableFuture<List<ModelInfo>>> getOnListModels()
      Gets the custom handler for listing available models.
      Returns:
      the handler, or null if not set

    • setOnListModels

      public CopilotClientOptions setOnListModels(Supplier<CompletableFuture<List<ModelInfo>>> onListModels)
      Sets a custom handler for listing available models.

      When provided, listModels() calls this handler instead of querying the CLI server. Useful in BYOK (Bring Your Own Key) mode to return models available from your custom provider.

      Parameters:
      onListModels - the handler that returns the list of available models (must not be null)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if onListModels is null

    • getRequestHandler

      public CopilotRequestHandler getRequestHandler()
      Gets the connection-level LLM inference request handler.
      Returns:
      the request handler, or null if not set

    • setRequestHandler

      public CopilotClientOptions setRequestHandler(CopilotRequestHandler requestHandler)
      Sets a connection-level LLM inference request handler.

      When provided, the client registers as the runtime's LLM inference provider on connect, and the runtime routes its model-layer HTTP and WebSocket traffic (both BYOK and CAPI) through the handler instead of issuing the calls itself.

      Parameters:
      requestHandler - the request handler (must not be null)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if requestHandler is null

    • getOnGitHubTelemetry

      @CopilotExperimental public Function<GitHubTelemetryNotification, CompletableFuture<Void>> getOnGitHubTelemetry()
      Gets the connection-level GitHub telemetry forwarding handler.

      Experimental: this option may change or be removed without notice.

      Returns:
      the async telemetry handler, or null if not set

    • setOnGitHubTelemetry

      @CopilotExperimental public CopilotClientOptions setOnGitHubTelemetry(Function<GitHubTelemetryNotification, CompletableFuture<Void>> onGitHubTelemetry)
      Sets a connection-level handler for GitHub telemetry forwarding (experimental).

      When provided, the client opts every session it creates or resumes into telemetry forwarding, and the runtime forwards each per-session telemetry event to this handler via the gitHubTelemetry.event notification. The handler returns a CompletableFuture that completes when asynchronous processing is finished.

      Parameters:
      onGitHubTelemetry - the async telemetry handler (must not be null)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if onGitHubTelemetry is null

    • getPort

      public int getPort()
      Gets the TCP port for the CLI server.
      Returns:
      the port number, or 0 for a random port

    • setPort

      public CopilotClientOptions setPort(int port)
      Sets the TCP port for the CLI server to listen on.

      This is only used when isUseStdio() is false.

      Parameters:
      port - the port number, or 0 for a random port
      Returns:
      this options instance for method chaining

    • isRemote

      public boolean isRemote()
      Returns whether remote session support (Mission Control integration) is enabled.

      When true, sessions in a GitHub repository working directory are accessible from GitHub web and mobile.

      Returns:
      true if remote sessions are enabled

    • setRemote

      public CopilotClientOptions setRemote(boolean remote)
      Enables remote session support (Mission Control integration).

      When true, sessions in a GitHub repository working directory are accessible from GitHub web and mobile.

      This option is only used when the SDK spawns the CLI process; it is ignored when connecting to an external server via setCliUrl(String).

      Parameters:
      remote - true to enable remote sessions
      Returns:
      this options instance for method chaining

    • getTelemetry

      public TelemetryConfig getTelemetry()
      Gets the OpenTelemetry configuration for the CLI server.
      Returns:
      the telemetry config, or null
      Since:
      1.0.0

    • setTelemetry

      public CopilotClientOptions setTelemetry(TelemetryConfig telemetry)
      Sets the OpenTelemetry configuration for the CLI server.

      When set, the CLI server is started with OpenTelemetry instrumentation enabled using the provided settings.

      Parameters:
      telemetry - the telemetry configuration
      Returns:
      this options instance for method chaining
      Since:
      1.0.0

    • getClientInfo

      public ClientInfo getClientInfo()
      Gets the integrating application's declared identity.
      Returns:
      the client info, or null
      Since:
      1.6.0

    • setClientInfo

      public CopilotClientOptions setClientInfo(ClientInfo clientInfo)
      Declares the integrating application's identity, forwarded to the runtime on the server.connect handshake.

      Declaring it lets the telemetry the runtime emits on this connection be attributed to a consistent surface (the application and its Copilot integration) instead of the runtime's own build. All fields on ClientInfo are optional; leave this unset to keep the runtime's default attribution.

      Parameters:
      clientInfo - the application identity to declare
      Returns:
      this options instance for method chaining
      Since:
      1.6.0

    • getSessionIdleTimeoutSeconds

      public OptionalInt getSessionIdleTimeoutSeconds()
      Gets the server-wide idle timeout for sessions in seconds.
      Returns:
      an OptionalInt containing the session idle timeout in seconds, or OptionalInt.empty() if not set. Use clearSessionIdleTimeoutSeconds() to revert to the default.
      Since:
      1.3.0

    • setSessionIdleTimeoutSeconds

      public CopilotClientOptions setSessionIdleTimeoutSeconds(int sessionIdleTimeoutSeconds)
      Sets the server-wide idle timeout for sessions in seconds.

      Sessions without activity for this duration are automatically cleaned up. Set to 0 to disable (sessions live indefinitely). Use clearSessionIdleTimeoutSeconds() to revert to the default.

      This option is only used when the SDK spawns the CLI process; it is ignored when connecting to an external server via setCliUrl(String).

      Parameters:
      sessionIdleTimeoutSeconds - the idle timeout in seconds
      Returns:
      this options instance for method chaining
      Since:
      1.3.0

    • clearSessionIdleTimeoutSeconds

      public CopilotClientOptions clearSessionIdleTimeoutSeconds()
      Clears the sessionIdleTimeoutSeconds setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getTcpConnectionToken

      public String getTcpConnectionToken()
      Gets the connection token for the headless CLI server (TCP only).
      Returns:
      the connection token, or null if not set

    • setTcpConnectionToken

      public CopilotClientOptions setTcpConnectionToken(String tcpConnectionToken)
      Sets the connection token for the headless CLI server (TCP only).

      When the SDK spawns its own CLI in TCP mode and this is omitted, a UUID is generated automatically so the loopback listener is safe by default. Cannot be combined with setUseStdio(boolean) = true.

      Parameters:
      tcpConnectionToken - the connection token (must not be null or empty)
      Returns:
      this options instance for method chaining

    • getUseLoggedInUser

      public Optional<Boolean> getUseLoggedInUser()
      Returns whether to use the logged-in user for authentication.
      Returns:
      an Optional containing the boolean value, or empty if not set

    • setUseLoggedInUser

      public CopilotClientOptions setUseLoggedInUser(boolean useLoggedInUser)
      Sets whether to use the logged-in user for authentication.

      When true, the CLI server will attempt to use stored OAuth tokens or gh CLI auth. When false, only explicit tokens (gitHubToken or environment variables) are used. Default: true (but defaults to false when gitHubToken is provided).

      Parameters:
      useLoggedInUser - true to use logged-in user auth, false otherwise
      Returns:
      this options instance for method chaining

    • clearUseLoggedInUser

      public CopilotClientOptions clearUseLoggedInUser()
      Clears the useLoggedInUser setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • isUseStdio

      public boolean isUseStdio()
      Returns whether to use stdio transport instead of TCP.
      Returns:
      true to use stdio (default), false to use TCP

    • setUseStdio

      public CopilotClientOptions setUseStdio(boolean useStdio)
      Sets whether to use stdio transport instead of TCP.

      Stdio transport is more efficient and is the default. TCP transport can be useful for debugging or connecting to remote servers.

      Parameters:
      useStdio - true to use stdio, false to use TCP
      Returns:
      this options instance for method chaining

    • clone

      public CopilotClientOptions clone()
      Creates a shallow clone of this CopilotClientOptions instance.

      Array properties (like cliArgs) are copied into new arrays so that modifications to the clone do not affect the original. The environment map is also copied to a new map instance. Other reference-type properties are shared between the original and clone.

      Returns:
      a clone of this options instance