From ee2e9474353384c688013fc30caeba9eba34767d Mon Sep 17 00:00:00 2001 From: Kiryl Dubarenka Date: Tue, 24 Feb 2026 05:35:25 -0800 Subject: [PATCH] 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 | 14 +++++++ docs/reference/configuration.md | 5 +++ packages/core/src/ide/process-utils.test.ts | 43 +++++++++++++++++++++ packages/core/src/ide/process-utils.ts | 20 ++++++++++ 4 files changed, 82 insertions(+) diff --git a/docs/ide-integration/index.md b/docs/ide-integration/index.md index c187a92f37..f16be2e730 100644 --- a/docs/ide-integration/index.md +++ b/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:** diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index ba22eb802f..077d8e6f66 100644 --- a/docs/reference/configuration.md +++ b/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. diff --git a/packages/core/src/ide/process-utils.test.ts b/packages/core/src/ide/process-utils.test.ts index 9176dad49e..db9f498286 100644 --- a/packages/core/src/ide/process-utils.test.ts +++ b/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', () => { diff --git a/packages/core/src/ide/process-utils.ts b/packages/core/src/ide/process-utils.ts index 4b4680df51..04670504b1 100644 --- a/packages/core/src/ide/process-utils.ts +++ b/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(); }