feat(ide): add GEMINI_CLI_IDE_PID env var to override IDE process detection (#15842)

Co-authored-by: Adib234 <30782825+Adib234@users.noreply.github.com>

docs/ide-integration/index.md

@@ -170,6 +170,20 @@ messages and how to resolve them.
   - **Solution:** Run `/ide enable` to try and reconnect. If the issue
     continues, open a new terminal window or restart your IDE.
 
+### Manual PID override
+
+If automatic IDE detection fails, or if you are running Gemini CLI in a
+standalone terminal and want to manually associate it with a specific IDE
+instance, you can set the `GEMINI_CLI_IDE_PID` environment variable to the
+process ID (PID) of your IDE.
+
+```bash
+export GEMINI_CLI_IDE_PID=12345
+```
+
+When this variable is set, Gemini CLI will skip automatic detection and attempt
+to connect using the provided PID.
+
 ### Configuration errors
 
 - **Message:**

docs/reference/configuration.md

@@ -1274,6 +1274,11 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
   - Specifies the default Gemini model to use.
   - Overrides the hardcoded default
   - Example: `export GEMINI_MODEL="gemini-3-flash-preview"`
+- **`GEMINI_CLI_IDE_PID`**:
+  - Manually specifies the PID of the IDE process to use for integration. This
+    is useful when running Gemini CLI in a standalone terminal while still
+    wanting to associate it with a specific IDE instance.
+  - Overrides the automatic IDE detection logic.
 - **`GEMINI_CLI_HOME`**:
   - Specifies the root directory for Gemini CLI's user-level configuration and
     storage.

packages/core/src/ide/process-utils.test.ts

@@ -34,6 +34,49 @@ describe('getIdeProcessInfo', () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  describe('GEMINI_CLI_IDE_PID override', () => {
+    it('should use GEMINI_CLI_IDE_PID and fetch command on Unix', async () => {
+      (os.platform as Mock).mockReturnValue('linux');
+      vi.stubEnv('GEMINI_CLI_IDE_PID', '12345');
+      mockedExec.mockResolvedValueOnce({ stdout: '0 my-ide-command' }); // getProcessInfo result
+
+      const result = await getIdeProcessInfo();
+
+      expect(result).toEqual({ pid: 12345, command: 'my-ide-command' });
+      expect(mockedExec).toHaveBeenCalledWith(
+        expect.stringContaining('ps -o ppid=,command= -p 12345'),
+      );
+    });
+
+    it('should use GEMINI_CLI_IDE_PID and fetch command on Windows', async () => {
+      (os.platform as Mock).mockReturnValue('win32');
+      vi.stubEnv('GEMINI_CLI_IDE_PID', '54321');
+      const processes = [
+        {
+          ProcessId: 54321,
+          ParentProcessId: 0,
+          Name: 'Code.exe',
+          CommandLine: 'C:\\Program Files\\VSCode\\Code.exe',
+        },
+      ];
+      mockedExec.mockResolvedValueOnce({ stdout: JSON.stringify(processes) });
+
+      const result = await getIdeProcessInfo();
+
+      expect(result).toEqual({
+        pid: 54321,
+        command: 'C:\\Program Files\\VSCode\\Code.exe',
+      });
+      expect(mockedExec).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine',
+        ),
+        expect.anything(),
+      );
+    });
   });
 
   describe('on Unix', () => {

packages/core/src/ide/process-utils.ts

@@ -208,6 +208,13 @@ async function getIdeProcessInfoForWindows(): Promise<{
  * to identify the main application process (e.g., the main VS Code window
  * process).
  *
+ * This function can be overridden by setting the `GEMINI_CLI_IDE_PID`
+ * environment variable. This is useful for launching Gemini CLI in a
+ * standalone terminal while still connecting to an IDE instance.
+ *
+ * If `GEMINI_CLI_IDE_PID` is set, the function uses that PID and fetches
+ * the command for it.
+ *
  * If the IDE process cannot be reliably identified, it will return the
  * top-level ancestor process ID and command as a fallback.
  *
@@ -219,6 +226,19 @@ export async function getIdeProcessInfo(): Promise<{
 }> {
   const platform = os.platform();
 
+  if (process.env['GEMINI_CLI_IDE_PID']) {
+    const idePid = parseInt(process.env['GEMINI_CLI_IDE_PID'], 10);
+    if (!isNaN(idePid) && idePid > 0) {
+      if (platform === 'win32') {
+        const processMap = await getProcessTableWindows();
+        const proc = processMap.get(idePid);
+        return { pid: idePid, command: proc?.command || '' };
+      }
+      const { command } = await getProcessInfo(idePid);
+      return { pid: idePid, command };
+    }
+  }
+
   if (platform === 'win32') {
     return getIdeProcessInfoForWindows();
   }