Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 evandro
|
2a5d482c52 | ||
|
evandro
|
9d1ce44ea3 |
@@ -1,366 +1,190 @@
|
|||||||
<p align="center">
|
<div align="center">
|
||||||
<img src="docs/assets/logo.png" alt="Gemini Nexus" width="128" height="128" />
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h1 align="center">Gemini Nexus</h1>
|
<img src="docs/assets/logo.png" width="110" alt="Gemini Nexus logo">
|
||||||
|
|
||||||
<p align="center">
|
<h1>Gemini Nexus</h1>
|
||||||
<strong>🚀 Professional multi-account AI gateway for Google Gemini & Claude</strong>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p align="center">
|
<p><strong>Desktop gateway that pools Google accounts behind a local OpenAI/Anthropic-compatible API, with encrypted credentials and auto-switching.</strong></p>
|
||||||
English | <a href="README.pt-BR.md">Português</a> | <a href="README.zh-CN.md">中文</a> | <a href="README.es.md">Español</a>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p align="center">
|
<a href="#-quickstart">Quickstart</a> ·
|
||||||
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
|
<a href="#-architecture">Architecture</a> ·
|
||||||
<img src="https://img.shields.io/github/v/release/evandrodevbr/GeminiNexus?style=flat-square" alt="Release" />
|
<a href="#-security-model">Security</a> ·
|
||||||
</a>
|
<a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a>
|
||||||
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
|
|
||||||
<img src="https://img.shields.io/github/downloads/evandrodevbr/GeminiNexus/total?style=flat-square&color=blue" alt="Downloads" />
|
|
||||||
</a>
|
|
||||||
<a href="https://github.com/evandrodevbr/GeminiNexus/blob/main/LICENSE">
|
|
||||||
<img src="https://img.shields.io/github/license/evandrodevbr/GeminiNexus?style=flat-square" alt="License" />
|
|
||||||
</a>
|
|
||||||
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational?style=flat-square" alt="Platform" />
|
|
||||||
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
|
|
||||||
</p>
|
|
||||||
|
|
||||||
> [!IMPORTANT]
|
|
||||||
> **Windows Users:** If you see a **"Windows protected your PC"** (SmartScreen) warning during installation, click **"More info"** and then **"Run anyway"**. This is an expected security prompt for new, unsigned applications.
|
|
||||||
|
|
||||||
|
|
||||||
---
|
<sub>English · <a href="README.pt-BR.md">Português</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.es.md">Español</a></sub>
|
||||||
|
|
||||||
## 📖 Table of Contents
|
</div>
|
||||||
|
|
||||||
- [✨ Why Gemini Nexus?](#-why-gemini-nexus)
|
<hr />
|
||||||
- [🎯 Features](#-features)
|
|
||||||
- [📸 Screenshots](#-screenshots)
|
|
||||||
- [⚡ Installation & Quick Start](#-installation--quick-start)
|
|
||||||
- [🛠️ Tech Stack](#️-tech-stack)
|
|
||||||
- [💻 Development](#-development)
|
|
||||||
- [❓ FAQ](#-faq)
|
|
||||||
- [🤝 Contributing](#-contributing)
|
|
||||||
- [📄 License](#-license)
|
|
||||||
|
|
||||||
---
|
## 📌 The problem
|
||||||
|
|
||||||
## ✨ Why Gemini Nexus?
|
Working with AI-powered IDEs and coding tools on a single Google 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 upstream. Gemini Nexus keeps all accounts in one pool, switches between them automatically and shows the traffic.
|
||||||
|
|
||||||
When using AI-powered IDEs and coding tools, have you ever run into these problems?
|
## ✨ What it does
|
||||||
|
|
||||||
- 😫 **Quota limits:** Single account quotas run out quickly, requiring frequent manual switching.
|
- **Pools** Google accounts added through OAuth, with status (Active, Rate Limited, Expired), last-used time and an optional per-account proxy URL.
|
||||||
- 🔄 **Account management:** Managing multiple Google/Claude accounts is cumbersome.
|
- **Switches** accounts automatically when quota drops below 5 % or an account is rate-limited; `CloudMonitorService` polls quota every 5 minutes.
|
||||||
- 📊 **Blind usage:** You don't know how much quota or how many tokens you've actually consumed.
|
- **Schedules** requests across the pool in `cache-first`, `balance` (default) or `performance-first` mode, with a per-account circuit breaker (default backoff 60 s → 5 min → 30 min → 2 h).
|
||||||
- 🔌 **Integration issues:** You need a reliable local API proxy that speaks OpenAI/Anthropic protocols natively.
|
- **Serves** `POST /v1/chat/completions` (OpenAI), `POST /v1/messages` (Anthropic), `GET /v1/models` and `GET /v1/models/capabilities`, so Cursor, Windsurf, OpenCode, Claude Code and similar clients can connect.
|
||||||
- 🔍 **Lack of transparency:** You can't see what's actually being sent or received by the proxy under the hood.
|
- **Maps** requested model names to upstream models through the `custom_mapping` and `anthropic_mapping` settings; request timeout defaults to 120 s.
|
||||||
|
- **Tracks** token usage per account and model, charts prompt and completion tokens, and estimates cost with editable per-model pricing.
|
||||||
|
- **Inspects** traffic (latency, status, model), replays logged requests and generates cURL and Python snippets plus an IDE Quick Setup.
|
||||||
|
- **Protects** stored credentials with AES-256-GCM and an OS-keychain master key (see [Security model](#-security-model)).
|
||||||
|
|
||||||
**Gemini Nexus** solves all of these issues. It's a professional Electron desktop application that acts as an intelligent gateway between your development tools and Google Gemini / Claude AI.
|
## 🖼️ Demo
|
||||||
|
|
||||||
### Key Value Proposition
|
<details>
|
||||||
|
<summary>Screenshots</summary>
|
||||||
|
|
||||||
- ✅ **Unlimited Account Pool** — Add any number of Google Gemini & Claude accounts.
|
<p align="center"><img src="docs/assets/main.png" alt="Main dashboard" width="80%"></p>
|
||||||
- ✅ **Smart Auto-Switching** — Automatically rotates to the next available account when quota is low or rate-limited.
|
<p align="center"><img src="docs/assets/2usage.png" alt="Usage analytics" width="80%"></p>
|
||||||
- ✅ **Real-time Usage Analytics** — SaaS-grade dashboard with area charts, trend indicators, and model distribution.
|
<p align="center"><img src="docs/assets/3proxy.png" alt="Proxy monitor" width="80%"></p>
|
||||||
- ✅ **Full Proxy Observability** — Live traffic monitor, request replay, and model capabilities inspector.
|
<p align="center"><img src="docs/assets/4routing.png" alt="Routing config" width="80%"></p>
|
||||||
- ✅ **OpenAI & Anthropic Compatible** — Drop-in replacement proxy for Cursor, Windsurf, OpenCode, and any OpenAI-compatible tool.
|
<p align="center"><img src="docs/assets/5docs.png" alt="Documentation" width="80%"></p>
|
||||||
- ✅ **Secure by Default** — AES-256-GCM encryption with OS-native credential management.
|
<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>
|
||||||
|
|
||||||
## 🎯 Features
|
## 🚀 Quickstart
|
||||||
|
|
||||||
<table>
|
**Use a release.** Download the build for your platform from [Releases](https://git.evandro.dev.br/evandro/gemini-nexus/releases), open the app, add at least one account, enable the proxy (it is disabled by default) and point your IDE at it:
|
||||||
<tr>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>☁️ Cloud Account Pool</h3>
|
|
||||||
<ul>
|
|
||||||
<li>Add unlimited Google Gemini / Claude accounts via OAuth</li>
|
|
||||||
<li>Display avatar, email, status, and last used time</li>
|
|
||||||
<li>Real-time status monitoring (Active, Rate Limited, Expired)</li>
|
|
||||||
<li>Per-account proxy URL configuration</li>
|
|
||||||
<li>Device identity profile management with history</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>📊 Usage Analytics Dashboard</h3>
|
|
||||||
<ul>
|
|
||||||
<li>Real-time token consumption with 15s auto-refresh</li>
|
|
||||||
<li>Area charts for daily/hourly prompt & completion tokens</li>
|
|
||||||
<li>Trend indicators (% change vs previous period)</li>
|
|
||||||
<li>Inline sparklines on stat cards</li>
|
|
||||||
<li>Model distribution ranking with horizontal bar charts</li>
|
|
||||||
<li>Prompt/Completion ratio visualization</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>🔌 Local API Proxy (Gateway)</h3>
|
|
||||||
<ul>
|
|
||||||
<li>OpenAI <code>/v1/chat/completions</code> compatible endpoint</li>
|
|
||||||
<li>Anthropic <code>/v1/messages</code> compatible endpoint</li>
|
|
||||||
<li>Full SSE streaming support (tested with Cursor, Windsurf, OpenCode)</li>
|
|
||||||
<li>Model mapping (e.g. <code>claude-sonnet-4-6</code> → <code>gemini-3-flash</code>)</li>
|
|
||||||
<li>Configurable port, timeout, and API key</li>
|
|
||||||
<li>Model visibility control (show/hide specific models)</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>🔄 Intelligent Auto-Switching</h3>
|
|
||||||
<ul>
|
|
||||||
<li>Unlimited pool mode with smart backup selection</li>
|
|
||||||
<li>Auto-switch when quota < 5% or rate-limited</li>
|
|
||||||
<li>Background monitoring every 5 minutes</li>
|
|
||||||
<li>Graceful fallback with status reason tracking</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>🔍 Proxy Observability (Advanced)</h3>
|
|
||||||
<ul>
|
|
||||||
<li><strong>Traffic Monitor</strong> — Live request/response log with latency, status, and model info</li>
|
|
||||||
<li><strong>Request Replay</strong> — Replay any recorded request for debugging</li>
|
|
||||||
<li><strong>Model Capabilities</strong> — Inspect vision, thinking, streaming, JSON mode support per model</li>
|
|
||||||
<li><strong>Developer Tools</strong> — cURL & Python code generation, one-click copy</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>🔐 Security & Encryption</h3>
|
|
||||||
<ul>
|
|
||||||
<li>AES-256-GCM encryption for all sensitive data</li>
|
|
||||||
<li>OS native credential manager integration (Keytar + SafeStorage)</li>
|
|
||||||
<li>Auto migration of legacy plaintext data</li>
|
|
||||||
<li>Encrypted token & quota storage per account</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>⚙️ Settings & Customization</h3>
|
|
||||||
<ul>
|
|
||||||
<li>Dark / Light / System theme support</li>
|
|
||||||
<li>Multi-language: English & Português (Brasil)</li>
|
|
||||||
<li>Per-account proxy URL override</li>
|
|
||||||
<li>Model visibility toggles</li>
|
|
||||||
<li>Log directory access</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
<td width="50%">
|
|
||||||
<h3>🖥️ Desktop Experience</h3>
|
|
||||||
<ul>
|
|
||||||
<li>Native Electron app with system tray integration</li>
|
|
||||||
<li>Collapsible sidebar with persistent state</li>
|
|
||||||
<li>Responsive layouts across all views</li>
|
|
||||||
<li>Status bar with live proxy and connection indicators</li>
|
|
||||||
<li>Error boundaries with user-friendly fallbacks</li>
|
|
||||||
</ul>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
---
|
```text
|
||||||
|
API Base URL: http://localhost:8045/v1 (default, configurable on the Proxy page; development builds use 8046)
|
||||||
## 📸 Screenshots
|
API Key: (copy it from the Proxy page in the app)
|
||||||
|
Model: gemini-3-flash (or any mapped model)
|
||||||
|
|
||||||
<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 Configuration" width="80%" />
|
|
||||||
</p>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚡ Installation & Quick Start
|
|
||||||
|
|
||||||
### 📦 Download the App
|
|
||||||
|
|
||||||
You can download the latest pre-compiled binaries for Windows, macOS, and Linux from our [Releases page](https://github.com/evandrodevbr/GeminiNexus/releases).
|
|
||||||
|
|
||||||
*(Refer to the warning at the top of this page if you are using Windows and encounter the SmartScreen prompt).*
|
|
||||||
|
|
||||||
### 🔌 Using with AI IDEs
|
|
||||||
|
|
||||||
Once the application is running and you have added at least one account, configure your preferred IDE (Cursor, Windsurf, OpenCode, etc.):
|
|
||||||
|
|
||||||
```plaintext
|
|
||||||
API Base URL: http://localhost:10100/v1
|
|
||||||
API Key: (copy this from the Proxy page in the app)
|
|
||||||
Model: gemini-3-flash (or any mapped model of your choice)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 🛠️ Build from Source
|
> [!WARNING]
|
||||||
|
> Builds are not code-signed. If Windows shows "Windows protected your PC", click **More info → Run anyway**.
|
||||||
|
|
||||||
#### Prerequisites
|
**Build from source.**
|
||||||
|
|
||||||
- **Node.js** v20 or higher
|
| Tool | Minimum version |
|
||||||
- **npm** (this project uses `package-lock.json`)
|
|---|---|
|
||||||
|
| Node.js | 20+ (recommended in `AGENTS.md`; `.nvmrc` pins 22.17.1) |
|
||||||
#### Steps
|
| pnpm | 10.11.0 (`packageManager`; lockfile is `pnpm-lock.yaml`) |
|
||||||
|
| Native toolchain | needed by `better-sqlite3` and `keytar`: Visual Studio 2022 Build Tools (C++) on Windows, Xcode Command Line Tools on macOS, `build-essential` + `python3` + `libsecret-1-dev` on Ubuntu (`base-devel` + `python` + `libsecret` on Arch) |
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
|
||||||
git clone https://github.com/evandrodevbr/GeminiNexus.git
|
cd gemini-nexus
|
||||||
cd GeminiNexus
|
pnpm install # postinstall runs scripts/setup-dev.js --check-only to verify the toolchain
|
||||||
|
pnpm start # dev mode (Electron + Vite HMR)
|
||||||
# Install dependencies
|
pnpm run make # installers/packages for the current platform
|
||||||
npm install
|
pnpm run make:win # Windows: extracts WiX from wix314-binaries.zip, then runs make
|
||||||
|
|
||||||
# Start the application in development mode
|
|
||||||
npm start
|
|
||||||
|
|
||||||
# Build for production (e.g., Windows installer)
|
|
||||||
npm run make
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
There is no `.env.example` and no variable is required. Optional variables read by the code or described in the docs:
|
||||||
|
|
||||||
## 🛠️ Tech Stack
|
| Variable | Required | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | No | Route the app's outbound requests through a local proxy (see [TLS inspection](#-security-model)). |
|
||||||
|
| `NODE_EXTRA_CA_CERTS` | No | Extra CA certificate for Node-side TLS when inspecting traffic. |
|
||||||
|
| `SENTRY_DSN` | No | Sentry DSN used when error reporting is enabled. |
|
||||||
|
|
||||||
| Category | Technologies |
|
## 🧱 Architecture
|
||||||
|----------|-------------|
|
|
||||||
| **Core** | [Electron](https://www.electronjs.org/), [React 19](https://react.dev/), [TypeScript](https://www.typescriptlang.org/) |
|
|
||||||
| **Build** | [Vite](https://vitejs.dev/), [Electron Forge](https://www.electronforge.io/) |
|
|
||||||
| **Styling** | [Tailwind CSS v4](https://tailwindcss.com/), [Radix UI](https://www.radix-ui.com/), [Lucide Icons](https://lucide.dev/) |
|
|
||||||
| **State** | [TanStack Query](https://tanstack.com/query/latest), [TanStack Router](https://tanstack.com/router/latest) |
|
|
||||||
| **Backend** | [NestJS](https://nestjs.com/) (internal gateway), [ORPC](https://orpc.unnoq.com/) (type-safe RPC) |
|
|
||||||
| **Database** | [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3), [Drizzle ORM](https://orm.drizzle.team/) |
|
|
||||||
| **Charts** | [Nivo](https://nivo.rocks/) (Line, Bar, Pie) |
|
|
||||||
| **i18n** | [react-i18next](https://react.i18next.com/) |
|
|
||||||
| **Testing** | [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/) |
|
|
||||||
|
|
||||||
---
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
## 💻 Development
|
C["Client: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["NestJS proxy, port 8045"]
|
||||||
|
P --> S["Account scheduler and circuit breaker"]
|
||||||
```bash
|
S -->|"Google OAuth account"| G["Google upstream APIs"]
|
||||||
# Start dev environment (Electron + Vite HMR)
|
M["CloudMonitor and AutoSwitch, quota every 5 min"] -->|"quota polling"| G
|
||||||
npm start
|
S -->|"reads accounts"| DB[("SQLite: better-sqlite3 and Drizzle")]
|
||||||
|
M --> DB
|
||||||
# Run linting
|
K["AES-256-GCM, master key in OS keychain"] -->|"encrypts tokens"| DB
|
||||||
npm run lint
|
|
||||||
|
|
||||||
# Type check
|
|
||||||
npm run type-check
|
|
||||||
|
|
||||||
# Format code
|
|
||||||
npm run format:write
|
|
||||||
|
|
||||||
# Run tests
|
|
||||||
npm test
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Project Structure
|
1. A client sends OpenAI- or Anthropic-format requests to the NestJS proxy (Fastify, bound to `0.0.0.0`).
|
||||||
|
2. The proxy guard checks the API key when one is configured; with an empty key the proxy runs in open mode.
|
||||||
|
3. The token manager picks an account according to the scheduling mode and each account's circuit-breaker state, then calls Google's upstream APIs with that account's OAuth token.
|
||||||
|
4. `CloudMonitorService` polls quota every 5 minutes and `AutoSwitchService` switches the active account when quota is below 5 % or the account is rate-limited.
|
||||||
|
5. The React 19 renderer (TanStack Router and Query) talks to the main process over oRPC on IPC; accounts, usage and settings live in SQLite (better-sqlite3 + Drizzle). Design notes: [`docs/cloud_features.md`](docs/cloud_features.md).
|
||||||
|
|
||||||
```plaintext
|
## 🔒 Security model
|
||||||
|
|
||||||
|
Gemini Nexus holds OAuth tokens for several accounts and forwards traffic upstream, so credential handling is the core of the design. Everything below is implemented in this repository; limits are stated where they exist.
|
||||||
|
|
||||||
|
- **Credential storage and isolation.** `token_json` and `quota_json` are encrypted with AES-256-GCM (unique IV per operation, authenticated) before they reach SQLite. The master key lives in the OS credential store through `keytar` (Windows Credential Manager, macOS Keychain, Linux Secret Service/libsecret), never in a plain file. Legacy plaintext rows are migrated at startup. Accounts are kept in their own database (`cloud_accounts.db`), independent from the IDE's local database.
|
||||||
|
- **Log masking.** Keys such as `token`, `refresh_token`, `api_key`, `authorization`, `cookie` and `client_secret` are replaced by `[REDACTED]` before logging ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); the traffic logger also redacts the `authorization`, `x-api-key` and `cookie` headers.
|
||||||
|
- **Request logging, not an audit trail.** Winston writes API, traffic and app logs to rotating files (API log: 30 days, 50 MB per file). These are operational logs, not a tamper-evident audit trail; the `*-audit.json` files are rotation bookkeeping from `winston-daily-rotate-file`.
|
||||||
|
- **Proxy access.** The proxy is off by default. Once enabled it listens on `0.0.0.0`, and requests are authenticated only when `api_key` is non-empty (empty means open mode). Set a key and keep it private.
|
||||||
|
- **TLS inspection (debugging only).** [`docs/proxyman-install.md`](docs/proxyman-install.md) and [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explain how to read the app's HTTPS traffic with Proxyman: trust its root CA, set the proxy variables and `NODE_EXTRA_CA_CERTS`, then start the app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (and the script's `-AllowInsecureTls` flag) is a temporary override; never leave it on. Do not commit proxy addresses, certificate paths, cookies or OAuth codes, and redact logs before sharing them. `scripts/start-antigravity-with-proxyman.ps1` targets the installed official Antigravity client, not this app.
|
||||||
|
- **Error reporting.** Sentry reports (they need `SENTRY_DSN`) are gated by the `error_reporting_enabled` setting, which `DEFAULT_APP_CONFIG` ships as `true`; turn it off in Settings to opt out. The Windows user-name segment is masked in reported exception messages.
|
||||||
|
|
||||||
|
Supported versions and how to report a vulnerability: [`SECURITY.md`](SECURITY.md).
|
||||||
|
|
||||||
|
## 🗂️ Structure
|
||||||
|
|
||||||
|
```text
|
||||||
src/
|
src/
|
||||||
├── actions/ # App actions and flow orchestration
|
├── components/ # UI (proxy/, usage/, ui/ primitives)
|
||||||
├── components/ # React UI components
|
├── ipc/ # oRPC routers (account, cloud, config, gateway, usage...)
|
||||||
│ ├── proxy/ # Proxy page components (advanced tabs)
|
├── server/ # NestJS proxy gateway (modules: proxy, usage)
|
||||||
│ ├── usage/ # Usage analytics components (StatCard, ChartCard)
|
├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
|
||||||
│ └── ui/ # Base UI primitives (Radix-based)
|
├── routes/ # index, usage, proxy, settings
|
||||||
├── hooks/ # Custom React hooks
|
├── utils/ # paths, logger, sensitiveDataMasking
|
||||||
├── ipc/ # Electron IPC + database handlers
|
└── tests/ # unit tests (Vitest) and E2E (Playwright)
|
||||||
├── layouts/ # Layout components (MainLayout + sidebar)
|
cli/ # separate Python CLI for account switching and quota checks
|
||||||
├── localization/ # i18n translation resources
|
docs/ # design notes and Proxyman guides
|
||||||
├── routes/ # TanStack Router pages (index, usage, proxy, settings)
|
scripts/ # setup-dev, build-windows, generate-assets
|
||||||
├── server/ # NestJS backend (proxy gateway service)
|
|
||||||
├── services/ # Service layer
|
|
||||||
├── types/ # TypeScript type definitions + Zod schemas
|
|
||||||
└── utils/ # Utility functions
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## 🧪 Scripts
|
||||||
|
|
||||||
## ❓ FAQ
|
| Command | What it does |
|
||||||
|
|---|---|
|
||||||
|
| `pnpm start` | Run the app in dev mode (`electron-forge start`, with `DEBUG=electron-forge:*`). |
|
||||||
|
| `pnpm run dev` | Same as `start`. |
|
||||||
|
| `pnpm run package` | Package the app with Electron Forge, without building installers. |
|
||||||
|
| `pnpm run make` | Build installers/packages for the current platform. |
|
||||||
|
| `pnpm run make:win` | Windows build helper: extracts WiX from `wix314-binaries.zip`, adds it to `PATH`, runs `electron-forge make`. |
|
||||||
|
| `pnpm run publish` | Publish through Electron Forge. |
|
||||||
|
| `pnpm run setup` | Run `scripts/setup-dev.js`: detect the native toolchain and install or guide the setup. |
|
||||||
|
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; runs automatically after `pnpm install`. |
|
||||||
|
| `pnpm run lint` | ESLint over the repo. |
|
||||||
|
| `pnpm run format` | Prettier check. |
|
||||||
|
| `pnpm run format:write` | Prettier write. |
|
||||||
|
| `pnpm test` | Vitest unit tests (`vitest run`). |
|
||||||
|
| `pnpm run test:watch` | Vitest in watch mode. |
|
||||||
|
| `pnpm run test:unit` | Vitest (default mode). |
|
||||||
|
| `pnpm run test:e2e` | Playwright E2E tests. |
|
||||||
|
| `pnpm run test:all` | Unit tests, then Playwright. |
|
||||||
|
| `pnpm run type-check` | `tsc --noEmit`. |
|
||||||
|
|
||||||
<details>
|
## 📚 Documentation
|
||||||
<summary><b>Q: "Windows protected your PC" (SmartScreen) warning during installation?</b></summary>
|
|
||||||
|
|
||||||
Yes, this is a common warning for new unsigned applications. Click **"More info"** and then **"Run anyway"**. See the warning at the top of the README for more details.
|
- [`docs/cloud_features.md`](docs/cloud_features.md): account pool, quota monitoring and auto-switch design.
|
||||||
</details>
|
- [`docs/proxyman-install.md`](docs/proxyman-install.md) and [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): TLS inspection setup (Windows).
|
||||||
|
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): OpenCode custom-endpoint integration (in Portuguese).
|
||||||
|
- [`cli/README.md`](cli/README.md): the Python command-line tool.
|
||||||
|
- [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`CHANGELOG.md`](CHANGELOG.md), [`LICENSE`](LICENSE), [`LICENSE-MIT`](LICENSE-MIT).
|
||||||
|
- Translations: [Português](README.pt-BR.md), [中文](README.zh-CN.md), [Español](README.es.md).
|
||||||
|
|
||||||
<details>
|
## 🛣️ Limitations and next steps
|
||||||
<summary><b>Q: The app won't start when building from source?</b></summary>
|
|
||||||
|
|
||||||
1. Make sure all dependencies are installed: `npm install`
|
- Upstream access goes through Google's `v1internal` Cloud Code endpoints and OAuth scopes ([`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.
|
||||||
2. Check if your Node.js version is >= 20.
|
- Accounts are added through Google OAuth; Claude models are reached through model mapping, not through separate Claude accounts.
|
||||||
3. Try deleting `node_modules` and reinstalling.
|
- End-to-end tests are not run in CI (Electron needs a graphical environment); run `pnpm run test:e2e` locally.
|
||||||
4. On Windows, ensure the WiX Toolset is available for `npm run make`.
|
- The Windows MSI is only produced when the WiX Toolset is available on the build machine; otherwise the Windows artifact is the ZIP.
|
||||||
</details>
|
- The workflows in `.github/workflows/` are written for GitHub (they call the `gh` CLI and the GitHub release publisher), so this README shows no CI badge.
|
||||||
|
- Next step stated by the project: migrate the remaining original code to MIT (see [License](#-license)).
|
||||||
<details>
|
|
||||||
<summary><b>Q: Account login failed?</b></summary>
|
|
||||||
|
|
||||||
1. Ensure your network connection is working.
|
|
||||||
2. Try clearing the app data and logging in again.
|
|
||||||
3. Check if the account is restricted by Google/Claude.
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><b>Q: My IDE can't connect to the proxy?</b></summary>
|
|
||||||
|
|
||||||
1. Make sure the proxy is actually running (look for the green indicator in the status bar).
|
|
||||||
2. Verify the port matches your IDE config (default is `10100`).
|
|
||||||
3. Copy the API key directly from the Proxy page and paste it into your IDE settings.
|
|
||||||
4. Check that at least one account is active in the Accounts page.
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><b>Q: Token counts are showing zero?</b></summary>
|
|
||||||
|
|
||||||
1. This was a known bug in earlier versions — please update to the latest release.
|
|
||||||
2. Token tracking now correctly handles streaming metadata and estimated counts.
|
|
||||||
3. Usage data refreshes every 15 seconds on the Usage Analytics page.
|
|
||||||
</details>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🤝 Contributing
|
## 🤝 Contributing
|
||||||
|
|
||||||
Contributions are welcome! Please read `CONTRIBUTING.md` for details.
|
Read [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Releases are versioned by semantic-release from Conventional Commits. Before opening a PR, these must pass:
|
||||||
|
|
||||||
---
|
```bash
|
||||||
|
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
|
||||||
|
```
|
||||||
|
|
||||||
## 📄 License
|
## 📄 License
|
||||||
|
|
||||||
This project uses a dual-license structure:
|
Mixed licensing: code inherited from [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (by Draculabo) is [CC BY-NC-SA 4.0](LICENSE) (non-commercial, share-alike); all new code is [MIT](LICENSE-MIT). The project is migrating to MIT as the remaining original code is rewritten, so check both files before any commercial use.
|
||||||
|
|
||||||
- **Original code** from [AntigravityManager](https://github.com/Draculabo/AntigravityManager) by [Draculabo](https://github.com/Draculabo): Licensed under [CC BY-NC-SA 4.0](LICENSE).
|
|
||||||
- **All new code, features, and architecture** by [evandrodevbr](https://github.com/evandrodevbr): Licensed under the [MIT License](LICENSE-MIT).
|
|
||||||
|
|
||||||
> 🔄 **Migration Notice:** This project is actively being migrated to a fully open-source license (MIT). As the remaining original code is progressively rewritten, the entire project will transition to MIT. We are committed to making Gemini Nexus 100% open-source.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🙏 Credits
|
|
||||||
|
|
||||||
This project was originally forked from [AntigravityManager](https://github.com/Draculabo/AntigravityManager) created by [Draculabo](https://github.com/Draculabo). The initial proxy concept and early Electron scaffolding were based on his work.
|
|
||||||
|
|
||||||
Since the fork, **the vast majority of the codebase has been rewritten, redesigned, and expanded** by [evandrodevbr](https://github.com/evandrodevbr), including but not limited to:
|
|
||||||
|
|
||||||
- Complete UI/UX redesign (navigation, accounts, usage analytics, proxy management)
|
|
||||||
- Usage Analytics dashboard with cost tracking, token averages, and OpenRouter integration
|
|
||||||
- Traffic monitor with per-request token/cost inspection
|
|
||||||
- Environment isolation (dev/prod), CI/CD pipeline, and test infrastructure
|
|
||||||
- IDE Quick Setup (OpenCode, Cursor, VS Code, Claude Code)
|
|
||||||
- Custom model pricing configuration
|
|
||||||
- All documentation and internationalization (EN, PT-BR, ES, ZH-CN)
|
|
||||||
Reference in new issue
Block a user