# How code-server --reuse-window and --new-window Flags Interact with Existing Instances > Learn how code-server --reuse-window and --new-window flags interact with existing instances. Discover how these flags forward requests to running servers instead of starting new processes. - Repository: [Coder/code-server](https://github.com/coder/code-server) - Tags: how-to-guide - Published: 2026-03-01 --- **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`](https://github.com/coder/code-server/blob/main/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: ```typescript 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`](https://github.com/coder/code-server/blob/main/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: ```typescript 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`](https://github.com/coder/code-server/blob/main/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: ```typescript 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`](https://github.com/coder/code-server/blob/main/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 ```bash # 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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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.