Gemini Nexus logo # Gemini Nexus **A desktop gateway that pools your Google Gemini and Claude accounts behind one local OpenAI- and Anthropic-compatible API — with automatic account switching, usage analytics and full traffic inspection.** ![Version](https://img.shields.io/badge/version-0.15.3-informational) ![Stack](https://img.shields.io/badge/Electron_41-React_19_%C2%B7_TypeScript-informational) ![License](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0_%2B_MIT-informational) English | [Português](README.pt-BR.md) | [中文](README.zh-CN.md) | [Español](README.es.md) [Install](#installation) · [Features](#features) · [How it works](#how-it-works) · [Build from source](#build-from-source) · [CI/CD](#cicd)
> [!NOTE] > **Project status:** actively released — current version is **0.15.3** (2026-05-02), > versioned automatically by semantic-release from Conventional Commits (see > [`CHANGELOG.md`](CHANGELOG.md)). The app started as a fork of > [AntigravityManager](https://github.com/Draculabo/AntigravityManager); most of the > code has since been rewritten (see [Licensing and credits](#licensing-and-credits)). > [!IMPORTANT] > **Mixed licensing.** Code inherited from AntigravityManager is under > **CC BY-NC-SA 4.0** ([`LICENSE`](LICENSE) — non-commercial, share-alike); all new > code is under **MIT** ([`LICENSE-MIT`](LICENSE-MIT)). The project is being migrated > to MIT as the remaining original code is rewritten. Check both files before any > commercial use. ## Why Gemini Nexus Working with AI-powered IDEs and coding tools on a single account means quota that runs out, manual account switching, no idea how many tokens you spent, and no view of what the proxy actually sends. Gemini Nexus puts all of that in one desktop app: - **Account pool** — add as many Google accounts as you need via OAuth. - **Smart auto-switching** — rotates to the next available account when quota is low or rate-limited. - **Drop-in local proxy** — speaks the OpenAI and Anthropic protocols, so Cursor, Windsurf, OpenCode and any compatible tool can point at it. - **Observability** — live traffic monitor, request replay and per-model capability inspector. - **Usage analytics** — token charts, trends and cost tracking. ## Features | Area | What you get | |---|---| | **Cloud account pool** | OAuth sign-in; avatar, email, status (Active / Rate Limited / Expired) and last-used time; per-account proxy URL; device identity profiles with history | | **Local API gateway** | `POST /v1/chat/completions` (OpenAI), `POST /v1/messages` (Anthropic), `GET /v1/models` and `GET /v1/models/capabilities`; SSE streaming; model mapping (e.g. `claude-sonnet-4-6` → `gemini-3-flash`); configurable port, timeout (default 120 s) and API key; per-model visibility | | **Auto-switching** | Switches when an account's quota drops below 5 % or it is rate-limited; background quota monitor every 5 minutes; scheduling modes `cache-first`, `balance` and `performance-first`; circuit breaker with 60 s → 5 min → 30 min → 2 h backoff | | **Usage analytics** | Token consumption charts (daily/hourly, prompt vs. completion), trend indicators, model ranking, cost tracking with custom model pricing | | **Proxy observability** | Traffic monitor (latency, status, model), request replay, model capabilities (vision, thinking, streaming, JSON mode), cURL and Python snippets, IDE Quick Setup (OpenCode, Cursor, VS Code, Claude Code) | | **Security** | AES-256-GCM for sensitive data, OS credential storage (Keytar + Electron SafeStorage), automatic migration of legacy plaintext data | | **Desktop experience** | System tray, dark / light / system theme, collapsible sidebar, status bar with live proxy indicators, UI in English, 简体中文, Русский and Tiếng Việt | The account-pool and auto-switching design is written up in [`docs/cloud_features.md`](docs/cloud_features.md).
Screenshots

Main dashboard

Usage analytics

Proxy monitor

Routing config

Documentation

Active connections

Settings

## Installation 1. Download the build for your platform from [**Releases**](https://git.evandro.dev.br/evandro/gemini-nexus/releases). The CI build matrix covers Windows (x64, arm64), macOS (x64, arm64) and Linux (x64, arm64); the configured makers produce MSI (Windows x64, only when WiX is available) and ZIP (Windows/macOS), DMG (macOS), AppImage, `.deb` and `.rpm` (Linux). 2. Open the app and add at least one account. 3. Enable the proxy and point your IDE at it: ```text API Base URL: http://localhost:8045/v1 (default port; configurable on the Proxy page) API Key: (copy it from the Proxy page in the app) Model: gemini-3-flash (or any mapped model) ``` > [!WARNING] > **Windows SmartScreen.** The builds are not code-signed. If Windows shows > **"Windows protected your PC"**, click **More info → Run anyway**. Separately, the > proxy is disabled by default; once enabled it listens on `0.0.0.0`, and requests > are only authenticated when an API key is configured (an empty key means open > mode) — set one and keep it private. ## How it works ```mermaid flowchart LR IDE["Cursor · Windsurf · OpenCode
Claude Code · any OpenAI/Anthropic client"] -->|"/v1/chat/completions
/v1/messages"| P subgraph APP["Gemini Nexus (Electron)"] R["Renderer
React 19 · TanStack Router/Query"] <-->|"oRPC over IPC"| M["Main process
config · tray · services"] M --> DB[("SQLite
better-sqlite3 + Drizzle")] M --> SEC["Encryption
AES-256-GCM · Keytar/SafeStorage"] M --> MON["CloudMonitor + AutoSwitch
quota every 5 min"] M --> P["NestJS proxy
port 8045"] P --> SCH["Account scheduler
+ circuit breaker"] end SCH -->|"Google OAuth account"| UP["Google upstream APIs"] MON --> UP ```
Stack and layout | Layer | Technology | |---|---| | Shell / build | Electron 41, Electron Forge, Vite 8 | | UI | React 19, TypeScript, Tailwind CSS 4, Radix UI, Nivo charts, react-i18next | | State / routing | TanStack Query, TanStack Router | | Backend | NestJS 11 (proxy gateway), oRPC (type-safe IPC) | | Data | better-sqlite3, Drizzle ORM | | Tests | Vitest (unit), Playwright (E2E) | ```text src/ ├── components/ # UI (proxy/, usage/, ui/ primitives) ├── ipc/ # oRPC routers: account, cloud, config, gateway, usage, proxy-advanced… ├── server/ # NestJS proxy gateway (modules: proxy, usage) ├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService ├── routes/ # index, usage, proxy, settings ├── localization/ # i18n resources └── types/ # types + Zod schemas ``` The `cli/` folder holds a separate Python command-line tool (Typer + Rich) for account switching and quota checks; see [`cli/README.md`](cli/README.md).
## Known limitations - Upstream access goes through Google's `v1internal` Cloud Code endpoints and OAuth scopes (see [`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). These are internal, undocumented APIs and may change without notice; the project is unofficial and not affiliated with Google or Anthropic. - End-to-end tests are not run in CI (Electron needs a graphical environment); run `pnpm run test:e2e` locally. - The Windows MSI is only produced when the WiX Toolset is available on the build machine; otherwise the Windows artifact is the ZIP. - Builds are unsigned, so Windows and macOS may show security prompts on first launch. ## Build from source Requirements: **Node.js ≥ 20** (`.nvmrc` pins 22.17.1) and **pnpm** (`packageManager: pnpm@10.11.0`; the lockfile is `pnpm-lock.yaml`). `pnpm install` runs [`scripts/setup-dev.js --check-only`](scripts/setup-dev.js), which verifies the native toolchain needed by `better-sqlite3` and `keytar`: Visual Studio 2022 Build Tools (C++) on Windows, Xcode Command Line Tools on macOS, and `build-essential`, `python3` and `libsecret-1-dev` on Ubuntu (`base-devel`, `python`, `libsecret` on Arch). ```bash git clone https://git.evandro.dev.br/evandro/gemini-nexus.git cd gemini-nexus pnpm install pnpm start # dev mode (Electron + Vite HMR) pnpm run make # build installers/packages for the current platform pnpm run make:win # Windows build helper (extracts WiX from wix314-binaries.zip) pnpm run lint # ESLint pnpm run type-check # tsc --noEmit pnpm run format:write pnpm test # Vitest unit tests pnpm run test:e2e # Playwright (local only) ```
FAQ **My IDE can't connect to the proxy.** Check that the proxy is running (green indicator in the status bar), that the port matches your IDE config (default `8045`), that you pasted the API key from the Proxy page, and that at least one account is active. **Account login failed.** Verify your network connection, clear the app data and sign in again, and check whether the account is restricted by the provider. **The app won't start when building from source.** Reinstall dependencies with `pnpm install`, confirm your Node.js version, and make sure the native toolchain listed above is installed.
## CI/CD Workflows in [`.github/workflows/`](.github/workflows): | Workflow | Trigger | What it does | |---|---|---| | [`format.yaml`](.github/workflows/format.yaml) | Pull request to `main` | Prettier check (`pnpm run format`) | | [`lint.yaml`](.github/workflows/lint.yaml) | Pull request to `main` | ESLint (`pnpm run lint`) | | [`testing.yaml`](.github/workflows/testing.yaml) | Push / PR to `main` | Unit tests (`pnpm test`) and type check (`pnpm run type-check`) | | [`release.yml`](.github/workflows/release.yml) | Push to `main`, manual | Semantic-release on Node 22, driven by [`release.config.cjs`](release.config.cjs): `feat` → minor; `fix`, `perf`, `style`, `refactor`, `build` → patch; `docs`, `test`, `ci`, `chore` → no release | | [`publish.yaml`](.github/workflows/publish.yaml) | After **Release** succeeds, manual (`dry_run` defaults to `true`) | Builds the 6-target matrix (Windows/macOS/Linux × x64/arm64) and uploads MSI, DMG, ZIP, AppImage, deb, rpm and update metadata to the release | These workflows are written for GitHub: they call the `gh` CLI and the GitHub release publisher. ## Licensing and credits - **Original code** from [AntigravityManager](https://github.com/Draculabo/AntigravityManager) by [Draculabo](https://github.com/Draculabo) — [CC BY-NC-SA 4.0](LICENSE). - **All new code, features and architecture** by [evandrodevbr](https://git.evandro.dev.br/evandro) — [MIT](LICENSE-MIT). The initial proxy concept and early Electron scaffolding came from AntigravityManager. Since the fork, the vast majority of the codebase has been rewritten, redesigned and expanded, including the UI/UX redesign, the usage analytics dashboard with cost tracking and OpenRouter pricing integration, the traffic monitor, dev/prod environment isolation, the CI/CD pipeline and test infrastructure, IDE Quick Setup, custom model pricing, and all documentation and its translations (EN, PT-BR, ES, ZH-CN). Contributing: see [`CONTRIBUTING.md`](CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) and [`SECURITY.md`](SECURITY.md). ## Notices - Unofficial project; not affiliated with Google or Anthropic. - Optional Sentry error reporting is controlled by the `error_reporting_enabled` setting; user paths are masked in reported events. - Built with [Electron](https://www.electronjs.org/), [Electron Forge](https://www.electronforge.io/), [NestJS](https://nestjs.com/), [oRPC](https://orpc.unnoq.com/) and [Drizzle ORM](https://orm.drizzle.team/).