gemini-nexus/README.md

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.

English | Português | 中文 | Español

Install · Features · How it works · Build from source · CI/CD

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). The app started as a fork of AntigravityManager; most of the code has since been rewritten (see Licensing and credits).

Important

Mixed licensing. Code inherited from AntigravityManager is under CC BY-NC-SA 4.0 (LICENSE — non-commercial, share-alike); all new code is under 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.

Screenshots

Installation

1. Download the build for your platform from 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:

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

flowchart LR
    IDE["Cursor · Windsurf · OpenCode<br/>Claude Code · any OpenAI/Anthropic client"] -->|"/v1/chat/completions<br/>/v1/messages"| P
    subgraph APP["Gemini Nexus (Electron)"]
        R["Renderer<br/>React 19 · TanStack Router/Query"] <-->|"oRPC over IPC"| M["Main process<br/>config · tray · services"]
        M --> DB[("SQLite<br/>better-sqlite3 + Drizzle")]
        M --> SEC["Encryption<br/>AES-256-GCM · Keytar/SafeStorage"]
        M --> MON["CloudMonitor + AutoSwitch<br/>quota every 5 min"]
        M --> P["NestJS proxy<br/>port 8045"]
        P --> SCH["Account scheduler<br/>+ 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)

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.

Known limitations

• Upstream access goes through Google's v1internal Cloud Code endpoints and OAuth scopes (see 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: [email protected]; the lockfile is pnpm-lock.yaml). pnpm install runs scripts/setup-dev.js --check-only, 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).

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/:

Workflow	Trigger	What it does
format.yaml	Pull request to main	Prettier check (pnpm run format)
lint.yaml	Pull request to main	ESLint (pnpm run lint)
testing.yaml	Push / PR to main	Unit tests (pnpm test) and type check (pnpm run type-check)
release.yml	Push to main, manual	Semantic-release on Node 22, driven by release.config.cjs: feat → minor; fix, perf, style, refactor, build → patch; docs, test, ci, chore → no release
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 by Draculabo — CC BY-NC-SA 4.0.
• All new code, features and architecture by evandrodevbr — 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, CODE_OF_CONDUCT.md and 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, Electron Forge, NestJS, oRPC and Drizzle ORM.