226 lines
12 KiB
Markdown
226 lines
12 KiB
Markdown
<div align="center">
|
||
|
||
<img src="docs/assets/logo.png" width="110" alt="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.**
|
||
|
||
|
||
|
||
|
||
|
||
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)
|
||
|
||
</div>
|
||
|
||
> [!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).
|
||
|
||
<details>
|
||
<summary>Screenshots</summary>
|
||
|
||
<p align="center"><img src="docs/assets/main.png" alt="Main dashboard" width="80%"></p>
|
||
<p align="center"><img src="docs/assets/2usage.png" alt="Usage analytics" width="80%"></p>
|
||
<p align="center"><img src="docs/assets/3proxy.png" alt="Proxy monitor" width="80%"></p>
|
||
<p align="center"><img src="docs/assets/4routing.png" alt="Routing config" width="80%"></p>
|
||
<p align="center"><img src="docs/assets/5docs.png" alt="Documentation" width="80%"></p>
|
||
<p align="center"><img src="docs/assets/6connections.png" alt="Active connections" width="80%"></p>
|
||
<p align="center"><img src="docs/assets/7config.png" alt="Settings" width="80%"></p>
|
||
|
||
</details>
|
||
|
||
## 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<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
|
||
```
|
||
|
||
<details>
|
||
<summary>Stack and layout</summary>
|
||
|
||
| 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).
|
||
|
||
</details>
|
||
|
||
## 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: [email protected]`; 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)
|
||
```
|
||
|
||
<details>
|
||
<summary>FAQ</summary>
|
||
|
||
**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.
|
||
|
||
</details>
|
||
|
||
## 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/).
|