feat: add Gemini CLI client adapter with configuration handling, installation detection, and preflight checks, refactorings, adding wizzard to mcp installation

Author: Cyneric

.gitignore

@@ -17,6 +17,13 @@ node_modules/
 .DS_Store
 Thumbs.db
 desktop.ini
+nul
+NUL
+
+# Windows temporary files
+*.tmp
+*.temp
+~$*
 
 # Logs
 logs/

src/main/__tests__/preload-bridge.test.ts

@@ -8,6 +8,8 @@ const EXPECTED_KEYS = [
   'clientsSync',
   'clientsSyncAll',
   'clientsPreviewConfigImport',
+  'clientsPreviewSync',
+  'clientsPreviewSyncAll',
   'clientsImportConfigChanges',
   'clientsSetManualConfigPath',
   'clientsClearManualConfigPath',
@@ -54,6 +56,17 @@ const EXPECTED_KEYS = [
   'registrySearch',
   'registryPrepareInstall',
   'registryInstall',
+  'installerPrepare',
+  'installerPreflight',
+  'installerRun',
+  'installerCancel',
+  'installerStatus',
+  'installerRepair',
+  'syncListPending',
+  'syncApplyPending',
+  'syncAutoPull',
+  'syncResolveConflict',
+  'syncPushReview',
   'stacksExport',
   'stacksImport',
   'backupsList',

src/main/clients/__tests__/client-install.service.test.ts

@@ -144,6 +144,22 @@ describe('ClientInstallService', () => {
     expect(spawnMock).not.toHaveBeenCalled()
   })
 
+  it('installs gemini-cli via npm when npm is available', async () => {
+    managerAvailability.winget = false
+    managerAvailability.choco = false
+    managerAvailability.npm = true
+    spawnPlanQueue.push({ command: 'npm', exitCode: 0, stdout: 'ok' })
+    const service = new ClientInstallService()
+
+    const result = await service.install('gemini-cli')
+
+    expect(result.success).toBe(true)
+    expect(result.installedWith).toBe('npm')
+    expect(result.attempts).toHaveLength(1)
+    expect(result.attempts[0]?.manager).toBe('npm')
+    expect(spawnMock).toHaveBeenCalledTimes(1)
+  })
+
   it('emits manager_skipped progress events when managers are unavailable', async () => {
     managerAvailability.winget = false
     managerAvailability.choco = false

src/main/clients/__tests__/gemini-cli.adapter.test.ts

@@ -0,0 +1,129 @@
+/**
+ * @file src/main/clients/__tests__/gemini-cli.adapter.test.ts
+ *
+ * @created 10.03.2026
+ * @modified 10.03.2026
+ *
+ * @author Christian Blank <christianblank91@protonmail.com>
+ * @copyright 2026
+ *
+ * @description Unit tests for the Gemini CLI client adapter.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdirSync, writeFileSync, rmSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { geminiCliAdapter } from '../gemini-cli.adapter'
+
+const makeTmpDir = (): string => {
+  const dir = join(tmpdir(), `gemini-test-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+describe('geminiCliAdapter', () => {
+  let tmpDir: string
+  let originalUserProfile: string | undefined
+  let originalPath: string | undefined
+  let originalPathExt: string | undefined
+  let originalAppData: string | undefined
+  let originalLocalAppData: string | undefined
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir()
+
+    originalUserProfile = process.env['USERPROFILE']
+    originalPath = process.env['PATH']
+    originalPathExt = process.env['PATHEXT']
+    originalAppData = process.env['APPDATA']
+    originalLocalAppData = process.env['LOCALAPPDATA']
+
+    process.env['USERPROFILE'] = join(tmpDir, 'user')
+    process.env['PATH'] = join(tmpDir, 'bin')
+    process.env['PATHEXT'] = '.EXE;.CMD;.BAT'
+    process.env['APPDATA'] = join(tmpDir, 'appdata')
+    process.env['LOCALAPPDATA'] = join(tmpDir, 'localappdata')
+  })
+
+  afterEach(() => {
+    process.env['USERPROFILE'] = originalUserProfile
+    process.env['PATH'] = originalPath
+    process.env['PATHEXT'] = originalPathExt
+    process.env['APPDATA'] = originalAppData
+    process.env['LOCALAPPDATA'] = originalLocalAppData
+    rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('reports not installed when config and executable are absent', async () => {
+    const result = await geminiCliAdapter.detect()
+    expect(result.installed).toBe(false)
+    expect(result.configPaths).toHaveLength(0)
+    expect(result.serverCount).toBe(0)
+  })
+
+  it('detects installed when gemini executable exists on PATH', async () => {
+    const binDir = process.env['PATH'] ?? ''
+    mkdirSync(binDir, { recursive: true })
+    writeFileSync(join(binDir, 'gemini.cmd'), '')
+
+    const result = await geminiCliAdapter.detect()
+    expect(result.installed).toBe(true)
+    expect(result.configPaths).toHaveLength(0)
+    expect(result.serverCount).toBe(0)
+  })
+
+  it('detects installed state from .gemini/settings.json', async () => {
+    const geminiDir = join(process.env['USERPROFILE'] ?? '', '.gemini')
+    mkdirSync(geminiDir, { recursive: true })
+    writeFileSync(
+      join(geminiDir, 'settings.json'),
+      JSON.stringify({ mcpServers: { tool: { command: 'npx', args: [] } } }),
+    )
+
+    const result = await geminiCliAdapter.detect()
+    expect(result.installed).toBe(true)
+    expect(result.configPaths).toHaveLength(1)
+    expect(result.serverCount).toBe(1)
+  })
+
+  it('reads mcpServers correctly', async () => {
+    const geminiDir = join(tmpDir, '.gemini')
+    const configFile = join(geminiDir, 'settings.json')
+    mkdirSync(geminiDir, { recursive: true })
+    writeFileSync(
+      configFile,
+      JSON.stringify({ mcpServers: { myTool: { command: 'node', args: ['server.js'] } } }),
+    )
+
+    const servers = await geminiCliAdapter.read(configFile)
+    expect(servers['myTool']?.command).toBe('node')
+  })
+
+  it('writes servers and preserves existing top-level keys', async () => {
+    const geminiDir = join(tmpDir, '.gemini')
+    const configFile = join(geminiDir, 'settings.json')
+    mkdirSync(geminiDir, { recursive: true })
+    writeFileSync(configFile, JSON.stringify({ model: 'gemini-2.5-pro' }))
+
+    await geminiCliAdapter.write(configFile, { newServer: { command: 'python', args: [] } })
+    const raw = JSON.parse(readFileSync(configFile, 'utf-8')) as {
+      model?: string
+      mcpServers?: Record<string, unknown>
+    }
+
+    expect(raw.model).toBe('gemini-2.5-pro')
+    expect(raw.mcpServers?.['newServer']).toBeDefined()
+  })
+
+  it('validate reports malformed json', async () => {
+    const geminiDir = join(tmpDir, '.gemini')
+    const configFile = join(geminiDir, 'settings.json')
+    mkdirSync(geminiDir, { recursive: true })
+    writeFileSync(configFile, '{ bad json')
+
+    const validation = await geminiCliAdapter.validate(configFile)
+    expect(validation.valid).toBe(false)
+    expect(validation.errors[0]).toContain('JSON parse error')
+  })
+})

src/main/clients/claude-desktop.adapter.ts

@@ -128,8 +128,14 @@ export const claudeDesktopAdapter: ClientAdapter = {
   read(configPath: string): Promise<McpServerMap> {
     if (!existsSync(configPath)) return Promise.resolve({})
 
-    const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as ClaudeConfig
-    return Promise.resolve((raw.mcpServers ?? {}) as McpServerMap)
+    try {
+      const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as ClaudeConfig
+      return Promise.resolve((raw.mcpServers ?? {}) as McpServerMap)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      log.warn(`[claude-desktop] failed to parse config ${configPath}: ${message}`)
+      return Promise.resolve({})
+    }
   },
 
   write(configPath: string, servers: McpServerMap): Promise<void> {

src/main/clients/client-install.service.ts

@@ -220,6 +220,16 @@ const INSTALL_DEFINITIONS: Readonly<Record<ClientId, ClientInstallDefinition>> =
     attempts: [],
     manualOnly: true,
   },
+  'gemini-cli': {
+    docsUrl: 'https://github.com/google-gemini/gemini-cli',
+    attempts: [
+      {
+        manager: 'npm',
+        command: 'npm',
+        args: ['install', '--global', '@google/gemini-cli', '--yes', '--silent'],
+      },
+    ],
+  },
   'codex-cli': {
     docsUrl: 'https://github.com/openai/codex',
     attempts: [

src/main/clients/gemini-cli.adapter.ts

@@ -0,0 +1,115 @@
+/**
+ * @file src/main/clients/gemini-cli.adapter.ts
+ *
+ * @created 10.03.2026
+ * @modified 10.03.2026
+ *
+ * @author Christian Blank <christianblank91@protonmail.com>
+ * @copyright 2026
+ *
+ * @description Client adapter for Gemini CLI. Config lives at
+ * `%USERPROFILE%\.gemini\settings.json` on Windows. MCP server definitions
+ * are stored under top-level `mcpServers`.
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import log from 'electron-log'
+import type { ClientDetectionResult, McpServerMap, ValidationResult } from '@shared/types'
+import type { ClientAdapter } from './types'
+import { hasWindowsCommandOnPath } from './windows-detection.util'
+
+interface GeminiConfig {
+  mcpServers?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+const configPath = (): string => join(process.env['USERPROFILE'] ?? '', '.gemini', 'settings.json')
+
+const isGeminiCliInstalled = (): boolean => {
+  if (process.platform !== 'win32') return false
+
+  const appData = process.env['APPDATA'] ?? ''
+  const localAppData = process.env['LOCALAPPDATA'] ?? ''
+  const candidates = [
+    join(appData, 'npm', 'gemini.cmd'),
+    join(appData, 'npm', 'gemini.exe'),
+    join(localAppData, 'Microsoft', 'WindowsApps', 'gemini.exe'),
+    join(localAppData, 'Microsoft', 'WindowsApps', 'gemini.cmd'),
+  ]
+
+  if (candidates.some((path) => existsSync(path))) {
+    return true
+  }
+
+  return hasWindowsCommandOnPath(['gemini'])
+}
+
+export const geminiCliAdapter: ClientAdapter = {
+  id: 'gemini-cli',
+  displayName: 'Gemini CLI',
+  schemaKey: 'mcpServers',
+
+  detect(): Promise<ClientDetectionResult> {
+    const path = configPath()
+    const hasConfig = existsSync(path)
+    const installed = hasConfig || isGeminiCliInstalled()
+    let serverCount = 0
+
+    if (hasConfig) {
+      try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8')) as GeminiConfig
+        serverCount = Object.keys(raw.mcpServers ?? {}).length
+      } catch {
+        serverCount = 0
+      }
+    }
+
+    log.debug(`[gemini-cli] detect: installed=${installed}, servers=${serverCount}`)
+
+    return Promise.resolve({
+      installed,
+      configPaths: hasConfig ? [path] : [],
+      serverCount,
+    })
+  },
+
+  read(configPath: string): Promise<McpServerMap> {
+    if (!existsSync(configPath)) return Promise.resolve({})
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as GeminiConfig
+    return Promise.resolve((raw.mcpServers ?? {}) as McpServerMap)
+  },
+
+  write(configPath: string, servers: McpServerMap): Promise<void> {
+    mkdirSync(dirname(configPath), { recursive: true })
+
+    let existing: GeminiConfig = {}
+    if (existsSync(configPath)) {
+      existing = JSON.parse(readFileSync(configPath, 'utf-8')) as GeminiConfig
+    }
+
+    const merged: GeminiConfig = { ...existing, mcpServers: servers }
+    const tmpPath = `${configPath}.aidrelay.tmp`
+    writeFileSync(tmpPath, JSON.stringify(merged, null, 2), 'utf-8')
+    renameSync(tmpPath, configPath)
+
+    log.info(`[gemini-cli] wrote ${Object.keys(servers).length} server(s) to ${configPath}`)
+    return Promise.resolve()
+  },
+
+  validate(configPath: string): Promise<ValidationResult> {
+    if (!existsSync(configPath)) {
+      return Promise.resolve({ valid: false, errors: [`Config file not found: ${configPath}`] })
+    }
+    try {
+      const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as GeminiConfig
+      if (raw.mcpServers !== undefined && typeof raw.mcpServers !== 'object') {
+        return Promise.resolve({ valid: false, errors: ['mcpServers must be an object'] })
+      }
+      return Promise.resolve({ valid: true, errors: [] })
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return Promise.resolve({ valid: false, errors: [`JSON parse error: ${message}`] })
+    }
+  },
+}

src/main/clients/registry.ts

@@ -21,6 +21,7 @@ import { vscodeInsidersAdapter } from './vscode-insiders.adapter'
 import { windsurfAdapter } from './windsurf.adapter'
 import { zedAdapter } from './zed.adapter'
 import { jetbrainsAdapter } from './jetbrains.adapter'
+import { geminiCliAdapter } from './gemini-cli.adapter'
 import { codexCliAdapter } from './codex-cli.adapter'
 import { codexGuiAdapter } from './codex-gui.adapter'
 import { opencodeAdapter } from './opencode.adapter'
@@ -39,6 +40,7 @@ export const ADAPTERS: Readonly<Map<ClientId, ClientAdapter>> = new Map<ClientId
   ['windsurf', windsurfAdapter],
   ['zed', zedAdapter],
   ['jetbrains', jetbrainsAdapter],
+  ['gemini-cli', geminiCliAdapter],
   ['codex-cli', codexCliAdapter],
   ['codex-gui', codexGuiAdapter],
   ['opencode', opencodeAdapter],
@@ -58,6 +60,7 @@ export const ADAPTER_IDS: readonly ClientId[] = [
   'windsurf',
   'zed',
   'jetbrains',
+  'gemini-cli',
   'codex-cli',
   'codex-gui',
   'opencode',

src/main/clients/vscode-insiders.adapter.ts

@@ -85,8 +85,14 @@ export const vscodeInsidersAdapter: ClientAdapter = {
   read(configPath: string): Promise<McpServerMap> {
     if (!existsSync(configPath)) return Promise.resolve({})
 
-    const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as VsCodeInsidersConfig
-    return Promise.resolve((raw.servers ?? {}) as McpServerMap)
+    try {
+      const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as VsCodeInsidersConfig
+      return Promise.resolve((raw.servers ?? {}) as McpServerMap)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      log.warn(`[vscode-insiders] failed to parse config ${configPath}: ${message}`)
+      return Promise.resolve({})
+    }
   },
 
   write(configPath: string, servers: McpServerMap): Promise<void> {