How code-server --reuse-window and --new-window Flags Interact with Existing Instances

When you invoke the code-server CLI with --reuse-window or --new-window, the command attempts to locate an already-running instance via the session socket and forwards the request rather than starting a new server process.

The coder/code-server project provides these flags to control window behavior when opening files or folders from the terminal. Understanding how --reuse-window and --new-window interact with existing instances helps you manage multiple workspaces without spawning redundant server processes.

How the CLI Detects Window Management Flags

The decision to forward a command to an existing instance begins in src/node/cli.ts within the shouldOpenInExistingInstance function. This logic determines whether the current invocation represents an "open in existing instance" request or requires a fresh server process.

Flag Detection Logic in cli.ts

The CLI first checks for the presence of either flag by iterating over the argument keys:

const openInFlagCount = ["reuse-window", "new-window"]
  .reduce((prev, cur) => (args[cur as keyof UserProvidedArgs] ? prev + 1 : prev), 0);

If openInFlagCount is greater than zero, the command is immediately flagged for forwarding to an existing instance rather than starting a new process. This check occurs around lines 45-56 of src/node/cli.ts, where the flag definitions themselves reside at lines 80-89.

Locating Active Instances via EditorSessionManager

Once the CLI identifies a window management flag, it attempts to locate a compatible running instance. This step is critical because these flags are designed to work only when a server is already active.

The Socket Path Resolution

The code contacts the EditorSessionManager through the session socket to request a connected socket capable of handling the first resolved path:

const socketPath = await client.getConnectedSocketPath(paths[0]);
if (!socketPath) {
  throw new Error(`No opened code-server instances found to handle ${paths[0]}`);
}
return socketPath;

If no suitable instance exists, the CLI throws an explicit error instead of silently starting a new server. This behavior mirrors VS Code's native implementation, ensuring that --reuse-window and --new-window strictly require an existing target.

Forwarding Requests to the Running Server

After locating a valid socket, the openInExistingInstance function in src/node/main.ts (around lines 78-85) constructs a pipe request containing the window management directives.

Building the OpenCommandPipeArgs

The CLI packages the flags into a structured request object:

const pipeArgs: OpenCommandPipeArgs & { fileURIs: string[] } = {
  type: "open",
  folderURIs: [],
  fileURIs: [],
  forceReuseWindow: args["reuse-window"],   // Maps to --reuse-window
  forceNewWindow: args["new-window"],       // Maps to --new-window
  gotoLineMode: true,
};

This request is POSTed to the existing server's root endpoint (/), allowing the VS Code window manager to honor the specified behavior.

Validation Constraints for --new-window

The CLI enforces a strict constraint at lines 95-98 of src/node/main.ts: the --new-window flag accepts only folder URIs. If you attempt to use it with file paths, the process aborts with the error:

--new-window can only be used with folder paths

Flag Precedence and Interaction

When both flags appear simultaneously, the CLI still routes the request to an existing instance (since openInFlagCount equals 2). However, the downstream VS Code implementation gives precedence to forceNewWindow, effectively ignoring the reuse request and creating a new window. This precedence matches the behavior in upstream VS Code, where --new-window wins when both flags are present.

The following scenarios illustrate the interaction:

• No flags: Spawns a brand-new code-server process (unless generic open-file heuristics find a compatible instance).
• --reuse-window only: Requires an existing instance; opens the target in the currently active window.
• --new-window only: Requires an existing instance; creates a new window for the specified folder.
• Both flags: Treated as an existing-instance request; the new-window directive takes precedence.

Practical Command Examples

# Reuse the current window of a running instance

code-server --reuse-window path/to/file.txt

# Open a folder in a new window of a running instance

code-server --new-window path/to/folder

# Both flags provided - new window wins

code-server --reuse-window --new-window path/to/folder

# Invalid - new-window requires a folder, not a file

code-server --new-window path/to/file.txt

# Error: --new-window can only be used with folder paths

Summary

• The shouldOpenInExistingInstance function in src/node/cli.ts detects window management flags by counting their presence in the argument object.
• When either --reuse-window or --new-window is set, the CLI must locate an existing instance via getConnectedSocketPath or throw an error.
• The openInExistingInstance function in src/node/main.ts forwards requests using OpenCommandPipeArgs with forceReuseWindow and forceNewWindow booleans.
• The --new-window flag strictly requires folder paths and creates a new workspace window in the existing instance.
• When both flags are present, forceNewWindow takes precedence, causing the existing instance to open a new window while ignoring the reuse directive.

Frequently Asked Questions

What happens if I use --reuse-window but no code-server instance is running?

The CLI throws an error stating No opened code-server instances found to handle [path]. Unlike standard file opening, these flags explicitly require an existing server process to receive the forwarded request.

Can I use --new-window to open individual files?

No. According to the validation logic in src/node/main.ts at lines 95-98, --new-window only accepts folder paths. Attempting to use it with file paths results in the error message --new-window can only be used with folder paths.

Which flag takes precedence if I specify both --reuse-window and --new-window?

The --new-window flag takes precedence. When both booleans are sent in the OpenCommandPipeArgs object, the VS Code window manager honors forceNewWindow and creates a new window, effectively ignoring the forceReuseWindow directive.

Do these flags start a new code-server process if no instance exists?

No. These flags are specifically designed to interact with existing instances. If no compatible socket is found via the EditorSessionManager, the CLI exits with an error rather than falling back to spawning a new server process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}