evandro/gemini-nexus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite READMEs with new logo, screenshots, and multi-language support

Browse Source
This commit is contained in:
Gemini Nexus Bot committed 2026-04-29 02:13:05 -03:00
1 parent e6f5adbae1
commit dc91cc9128
15 files changed
+931 -120
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+176 -69
View File
@@ -5,20 +5,14 @@
<h1 align="center">Gemini Nexus</h1>
<p align="center">
<strong>🚀 Professional multi-account manager for Google Gemini & Claude AI</strong>
<strong>🚀 Professional multi-account AI gateway for Google Gemini & Claude</strong>
</p>
<p align="center">
English | <a href="README.pt-BR.md">Português (Brasil)</a>
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="https://github.com/Draculabo/GeminiNexus/actions/workflows/testing.yaml">
<img src="https://github.com/Draculabo/GeminiNexus/actions/workflows/testing.yaml/badge.svg" alt="Tests" />
</a>
<a href="https://github.com/Draculabo/GeminiNexus/actions/workflows/lint.yaml">
<img src="https://github.com/Draculabo/GeminiNexus/actions/workflows/lint.yaml/badge.svg" alt="Lint" />
</a>
<a href="https://github.com/Draculabo/GeminiNexus/releases">
<img src="https://img.shields.io/github/v/release/Draculabo/GeminiNexus?style=flat-square" alt="Release" />
</a>
@@ -28,6 +22,8 @@
<a href="https://github.com/Draculabo/GeminiNexus/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/Draculabo/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>
---
@@ -35,13 +31,11 @@
## 📖 Table of Contents
- [Why Gemini Nexus?](#-why-gemini-nexus)
- [Improvements over Base Project](#-improvements-over-base-project)
- [Features](#-features)
- [Screenshots](#-screenshots)
- [Quick Start](#-quick-start)
- [Tech Stack](#️-tech-stack)
- [Development](#-development)
- [Debugging Docs](#-debugging-docs)
- [FAQ](#-faq)
- [Contributing](#-contributing)
- [License](#-license)
@@ -50,34 +44,22 @@
## ✨ Why Gemini Nexus?
When using your favorite IDEs, have you ever encountered these problems?
When using AI-powered IDEs and coding tools, have you ever run into these problems?
- 😫 Single account quota runs out quickly, requiring frequent manual switching
- 🔄 Managing multiple Google/Claude accounts is cumbersome
- 📊 Don't know how much quota is left on the current account
- ⏰ Worried about missing quota reset times
- 🔌 Need a reliable local API proxy for development tools
- 📊 Don't know how much quota or tokens you've consumed
- 🔌 Need a reliable local API proxy that speaks OpenAI/Anthropic protocols
- 🔍 Can't see what's actually being sent/received by the proxy
**Gemini Nexus** is here to solve these problems! It's a professional Electron desktop app that helps you:
**Gemini Nexus** solves all of these. It's a professional Electron desktop application that acts as an intelligent gateway between your development tools and Google Gemini / Claude AI:
- ✅ **Unlimited Account Pool** - Add any number of Google Gemini / Claude accounts
- ✅ **Smart Auto-Switching** - Automatically switch to the next available account when quota is low or rate-limited
- ✅ **Real-time Monitoring** - Visualize quota usage for all accounts
- ✅ **Local API Proxy** - Built-in OpenAI/Anthropic compatible proxy server
- ✅ **Secure Encryption** - AES-256-GCM encryption for sensitive data
---
## 🌟 Improvements over Base Project
This project contains significant development improvements, bug fixes, and configuration enhancements compared to the original base project.
Key improvements include:
- **Enhanced API Management UI:** Implemented dynamic model selectors and "Copy API Name" features to streamline integration with other tools.
- **Robust SSE Streaming:** Fixed critical Server-Sent Events (SSE) streaming bugs in the `/v1/chat/completions` proxy endpoint to perfectly support IDEs like Cursor, OpenCode, and Windsurf.
- **Rebranding and Localization:** Complete rebranding to Gemini Nexus with improved Portuguese (Brazil) localization and English defaults.
- **Agentic Capabilities:** Integration of advanced AI developer agents and skill frameworks (GSD, AutoResearch, Superpowers) directly into the project ecosystem for rapid autonomous development.
- **Build & Dev Env:** Better cross-platform build configurations, updated schemas, and automated toolchain processes.
- ✅ **Unlimited Account Pool** — Add any number of Google Gemini & Claude accounts
- ✅ **Smart Auto-Switching** — Automatically rotates to the next available account when quota is low or rate-limited
- ✅ **Real-time Usage Analytics** — SaaS-grade dashboard with area charts, trend indicators, and model distribution
- ✅ **Full Proxy Observability** — Live traffic monitor, request replay, and model capabilities inspector
- ✅ **OpenAI & Anthropic Compatible** — Drop-in replacement proxy for Cursor, Windsurf, OpenCode, and any OpenAI-compatible tool
- ✅ **Secure by Default** — AES-256-GCM encryption with OS-native credential management
---
@@ -91,50 +73,83 @@ Key improvements include:
<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>📊 Real-time Quota Monitoring</h3>
<h3>📊 Usage Analytics Dashboard</h3>
<ul>
<li>Multi-model support: gemini-pro, claude-3-5-sonnet, etc.</li>
<li>Visual progress bars with color indicators</li>
<li>Auto & manual refresh capabilities</li>
<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>
</ul>
</td>
<td width="50%">
<h3>🔐 Security First</h3>
<ul>
<li>AES-256-GCM encryption for sensitive data</li>
<li>OS native credential manager integration</li>
<li>Auto migration of legacy plaintext data</li>
<li>Graceful fallback with status reason tracking</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>🔌 Local API Proxy</h3>
<h3>🔍 Proxy Observability (Advanced)</h3>
<ul>
<li>OpenAI & Anthropic API compatible</li>
<li>Configurable port and request timeout</li>
<li>Model mapping (e.g. Claude → Gemini)</li>
<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>🛠️ Developer Tools</h3>
<h3>🔐 Security & Encryption</h3>
<ul>
<li>Built-in cURL & Python code generation</li>
<li>Visual service status monitoring</li>
<li>One-click API Key regeneration</li>
<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>
@@ -144,23 +159,40 @@ Key improvements include:
## 📸 Screenshots
<p align="center">
<img src="docs/assets/screenshot-main.png" alt="Main Interface" width="80%" />
<img src="docs/assets/main.png" alt="Main" width="80%" />
</p>
<p align="center">
<img src="docs/assets/2usage.png" alt="Usage" width="80%" />
</p>
<p align="center">
<img src="docs/assets/3proxy.png" alt="Proxy" width="80%" />
</p>
<p align="center">
<img src="docs/assets/4routing.png" alt="Routing" width="80%" />
</p>
<p align="center">
<img src="docs/assets/5docs.png" alt="Docs" width="80%" />
</p>
<p align="center">
<img src="docs/assets/6connections.png" alt="Connections" width="80%" />
</p>
<p align="center">
<img src="docs/assets/7config.png" alt="Config" width="80%" />
</p>
---
## ⚡ Quick Start
### Prerequisites
- **Node.js** v20 or higher
- **npm** (this project uses `package-lock.json`)
### Build from Source
#### Prerequisites
- Node.js v18 or higher
- npm or pnpm
#### Steps
```bash
# Clone the repository
git clone https://github.com/Draculabo/GeminiNexus.git
@@ -172,21 +204,77 @@ npm install
# Start development
npm start
# Build for production
# Build for production (Windows installer)
npm run make
```
### Using with AI IDEs
Once the proxy is running, configure your IDE:
```plaintext
# In Cursor / Windsurf / OpenCode settings:
API Base URL: http://localhost:10100/v1
API Key: (copy from the Proxy page in the app)
Model: gemini-3-flash (or any mapped model)
```
---
## 🛠️ Tech Stack
| Category | Technologies |
|----------|-------------|
| **Core** | [Electron](https://www.electronjs.org/), [React](https://react.dev/), [TypeScript](https://www.typescriptlang.org/) |
| **Build Tool** | [Vite](https://vitejs.dev/) |
| **Styling** | [TailwindCSS](https://tailwindcss.com/), [Shadcn UI](https://ui.shadcn.com/) |
| **State** | [TanStack Query](https://tanstack.com/query/latest) |
| **Database** | [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3) |
| **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/) |
---
## 💻 Development
```bash
# Start dev environment (Electron + Vite HMR)
npm start
# Run linting
npm run lint
# Type check
npm run type-check
# Format code
npm run format:write
# Run tests
npm test
```
### Project Structure
```plaintext
src/
├── actions/ # App actions and flow orchestration
├── components/ # React UI components
│ ├── proxy/ # Proxy page components (advanced tabs)
│ ├── usage/ # Usage analytics components (StatCard, ChartCard)
│ └── ui/ # Base UI primitives (Radix-based)
├── hooks/ # Custom React hooks
├── ipc/ # Electron IPC + database handlers
├── layouts/ # Layout components (MainLayout + sidebar)
├── localization/ # i18n translation resources
├── routes/ # TanStack Router pages (index, usage, proxy, settings)
├── server/ # NestJS backend (proxy gateway service)
├── services/ # Service layer
├── types/ # TypeScript type definitions + Zod schemas
└── utils/ # Utility functions
```
---
@@ -195,10 +283,10 @@ npm run make
<details>
<summary><b>Q: The app won't start?</b></summary>
Please check:
1. Make sure all dependencies are installed: `npm install`
2. Check if Node.js version is >= 18
2. Check if Node.js version is >= 20
3. Try deleting `node_modules` and reinstalling
4. On Windows, ensure the WiX Toolset is available for `npm run make`
</details>
@@ -211,6 +299,25 @@ Please check:
</details>
<details>
<summary><b>Q: IDE can't connect to the proxy?</b></summary>
1. Make sure the proxy is running (green indicator in the status bar)
2. Verify the port matches your IDE config (default: `10100`)
3. Copy the API key from the Proxy page and paste it in your IDE settings
4. Check that at least one account is active in the Accounts page
</details>
<details>
<summary><b>Q: Token counts show zero?</b></summary>
1. This was a known bug in earlier versions — update to the latest version
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