+English · Português · 中文 · Español
-> [!IMPORTANT]
-> **Usuarios de Windows:** Si ves una advertencia de SmartScreen **"Windows protegió su PC"** durante la instalación, haz clic en **"Más información"** y luego en **"Ejecutar de todas formas"**. Esta es una advertencia de seguridad esperada para aplicaciones nuevas no firmadas.
+
----
+## 📸 Capturas de pantalla
-## 📖 Tabla de Contenidos
+
-## ✨ ¿Por qué Gemini Nexus?
-
-Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con estos problemas?
-
-- 😫 **Límites de cuota:** La cuota de una sola cuenta se agota rápido, requiriendo cambios manuales frecuentes.
-- 🔄 **Gestión de cuentas:** Gestionar múltiples cuentas de Google/Claude es tedioso.
-- 📊 **Uso a ciegas:** No sabes cuántos tokens has consumido o cuánta cuota queda.
-- 🔌 **Problemas de integración:** Necesitas un proxy local confiable que hable los protocolos OpenAI/Anthropic de forma nativa.
-- 🔍 **Falta de transparencia:** No puedes ver qué se envía o recibe exactamente a través del proxy.
-
-**Gemini Nexus** resuelve todo esto. Es una aplicación de escritorio profesional en Electron que actúa como gateway inteligente entre tus herramientas de desarrollo y Google Gemini / Claude AI.
-
-### Propuesta de Valor
-
-- ✅ **Pool de Cuentas Ilimitado** — Agrega cualquier cantidad de cuentas Google Gemini y Claude.
-- ✅ **Cambio Automático Inteligente** — Rota automáticamente a la siguiente cuenta disponible cuando la cuota es baja o hay rate limit.
-- ✅ **Analytics de Uso en Tiempo Real** — Dashboard nivel SaaS con gráficos de área, indicadores de tendencia y distribución por modelo.
-- ✅ **Observabilidad Completa del Proxy** — Monitor de tráfico en vivo, replay de solicitudes e inspector de capacidades de modelos.
-- ✅ **Compatible con OpenAI y Anthropic** — Proxy drop-in para Cursor, Windsurf, OpenCode y cualquier herramienta compatible con OpenAI.
-- ✅ **Seguro por Defecto** — Cifrado AES-256-GCM con gestión nativa de credenciales del sistema operativo.
-
----
+
## 🎯 Características
+Trabajar con IDEs con IA sobre una sola cuenta de Google significa cuota que se agota, cambios de cuenta manuales y ninguna visibilidad de lo que el proxy envía hacia arriba. Gemini Nexus reúne todas las cuentas en un pool y las sirve por un único endpoint local.
+
-
-
-
☁️ Pool de Cuentas en la Nube
-
-
Agrega cuentas ilimitadas de Google Gemini / Claude vía OAuth
-
Muestra avatar, email, estado y último uso
-
Monitoreo de estado en tiempo real (Activa, Rate Limited, Expirada)
-
Configuración de proxy URL por cuenta
-
Gestión de perfil de identidad del dispositivo con historial
-
-
-
-
📊 Dashboard de Analytics de Uso
-
-
Consumo de tokens en tiempo real con auto-refresh cada 15s
-
Gráficos de área para tokens de prompt y completion (diario/horario)
-
Indicadores de tendencia (% de cambio vs período anterior)
-
Sparklines inline en las tarjetas de estadísticas
-
Ranking de distribución por modelo con gráficos de barras horizontales
-
Visualización de proporción Prompt/Completion
-
-
-
-
-
-
🔌 Proxy de API Local (Gateway)
-
-
Endpoint compatible con OpenAI /v1/chat/completions
-
Endpoint compatible con Anthropic /v1/messages
-
Soporte completo de streaming SSE (probado con Cursor, Windsurf, OpenCode)
-
Mapeo de modelos (ej: claude-sonnet-4-6 → gemini-3-flash)
-
Puerto, timeout y API key configurables
-
Control de visibilidad de modelos
-
-
-
-
🔄 Cambio Automático Inteligente
-
-
Modo pool ilimitado con selección inteligente de respaldo
-
Cambio automático cuando cuota < 5% o con rate limit
-
Monitoreo en segundo plano cada 5 minutos
-
Fallback elegante con seguimiento de razón de estado
-
-
-
-
-
-
🔍 Observabilidad del Proxy (Avanzado)
-
-
Monitor de Tráfico — Log en vivo de solicitudes/respuestas con latencia y modelo
-
Replay de Solicitudes — Reproduce cualquier solicitud para debugging
-
Capacidades de Modelos — Inspecciona soporte de visión, thinking, streaming, modo JSON
-
Herramientas para Devs — Generación de código cURL y Python, copia con un clic
-
-
-
-
🔐 Seguridad y Cifrado
-
-
Cifrado AES-256-GCM para todos los datos sensibles
-
Integración con gestor de credenciales nativo del SO (Keytar + SafeStorage)
-
Migración automática de datos legacy en texto plano
-
Almacenamiento cifrado de tokens y cuotas por cuenta
-
-
-
-
-
-
⚙️ Configuración y Personalización
-
-
Soporte de temas Oscuro / Claro / Sistema
-
Multi-idioma: English & Português (Brasil)
-
Override de proxy URL por cuenta
-
Toggles de visibilidad de modelos
-
Acceso al directorio de logs
-
-
-
-
🖥️ Experiencia de Escritorio
-
-
App nativa Electron con integración en bandeja del sistema
-
Sidebar colapsable con estado persistente
-
Layouts responsivos en todas las vistas
-
Barra de estado con indicadores en vivo de proxy y conexión
-
Error boundaries con fallbacks amigables al usuario
-
-
-
+
+
Un endpoint local POST /v1/chat/completions (OpenAI), POST /v1/messages (Anthropic), GET /v1/models y GET /v1/models/capabilities, para que Cursor, Windsurf, OpenCode, Claude Code y clientes similares puedan conectarse. Los nombres de modelo se mapean con custom_mapping y anthropic_mapping.
+
Pool de cuentas Cuentas de Google añadidas por OAuth, cada una con su estado (Active, Rate Limited, Expired), hora del último uso y una URL de proxy opcional por cuenta.
+
+
+
Cambio automático CloudMonitorService consulta la cuota cada 5 minutos y AutoSwitchService pasa a otra cuenta cuando la cuota baja del 5 % o la cuenta sufre rate limit.
+
Planificación con circuit breaker cache-first, balance (por defecto) o performance-first, con circuit breaker por cuenta (backoff por defecto 60 s → 5 min → 30 min → 2 h).
+
+
+
Uso y coste Consumo de tokens por cuenta y por modelo, gráficos de prompt y completion y estimación de coste con precios por modelo editables.
+
Inspector de tráfico Latencia, estado y modelo de cada petición, replay de peticiones registradas, snippets cURL y Python generados y un Quick Setup para IDEs.
+
----
+Las credenciales guardadas se cifran con AES-256-GCM bajo una clave maestra en el llavero del sistema (ver [Modelo de seguridad](#modelo-de-seguridad)).
-## 📸 Capturas de Pantalla
+## Cómo funciona
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+1. **Añade cuentas.** Inicia sesión con Google OAuth en la página Accounts. Los tokens se cifran antes de llegar a SQLite.
+2. **Apunta tu IDE al proxy.** Activa el proxy en la página Proxy (viene apagado) y usa `http://localhost:8045/v1` con la API key que se muestra allí, en formato OpenAI o Anthropic.
+3. **Nexus enruta cada petición.** El token manager elige una cuenta según el modo de planificación y el estado del circuit breaker, llama a las APIs upstream de Google con el token OAuth de esa cuenta, y el cambio automático actúa cuando la cuota baja del 5 % o una cuenta sufre rate limit.
----
+El flujo completo, con los componentes implicados, está en [Arquitectura](#arquitectura).
-## ⚡ Instalación e Inicio Rápido
+## ⚡ Inicio rápido
-### 📦 Descarga
+Todavía no hay descargas precompiladas en la página de [Releases de Gitea](https://git.evandro.dev.br/evandro/gemini-nexus/releases) (los workflows de release en `.github/workflows/` apuntan a GitHub), así que compila desde el código fuente.
-Puedes descargar los binarios precompilados más recientes para Windows, macOS y Linux desde nuestra [página de Releases](https://github.com/evandrodevbr/GeminiNexus/releases).
-
-*(Consulta la advertencia en la parte superior de esta página si usas Windows y te encuentras con el aviso de SmartScreen).*
-
-### 🔌 Uso con IDEs de IA
-
-Con la aplicación en ejecución y al menos una cuenta agregada, configura tu IDE preferido (Cursor, Windsurf, OpenCode, etc.):
-
-```plaintext
-API Base URL: http://localhost:10100/v1
-API Key: (copiar de la página Proxy en la app)
-Model: gemini-3-flash (o cualquier modelo mapeado)
-```
-
-### 🛠️ Compilar desde el Código Fuente
-
-#### Requisitos Previos
-
-- **Node.js** v20 o superior
-- **npm** (este proyecto usa `package-lock.json`)
-
-#### Pasos
+| Herramienta | Versión mínima |
+|---|---|
+| Node.js | 20+ (recomendado en `AGENTS.md`; `.nvmrc` fija 22.17.1) |
+| pnpm | 10.11.0 (`packageManager`; el lockfile es `pnpm-lock.yaml`) |
+| Toolchain nativa | necesaria para `better-sqlite3` y `keytar`: Visual Studio 2022 Build Tools (C++) en Windows, Xcode Command Line Tools en macOS, `build-essential` + `python3` + `libsecret-1-dev` en Ubuntu (`base-devel` + `python` + `libsecret` en Arch) |
```bash
-# Clonar el repositorio
-git clone https://github.com/evandrodevbr/GeminiNexus.git
-cd GeminiNexus
-
-# Instalar dependencias
-npm install
-
-# Iniciar en modo desarrollo
-npm start
-
-# Compilar para producción (ej: instalador de Windows)
-npm run make
+git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
+cd gemini-nexus
+pnpm install # el postinstall ejecuta scripts/setup-dev.js --check-only para verificar la toolchain
+pnpm start # modo dev (Electron + Vite HMR)
+pnpm run make # instaladores/paquetes para la plataforma actual
+pnpm run make:win # Windows: extrae WiX de wix314-binaries.zip y luego ejecuta make
```
----
+Después añade al menos una cuenta, activa el proxy (viene apagado) y apunta tu IDE a él:
-## 🛠️ Stack Tecnológico
-
-| Categoría | Tecnologías |
-| ----------------- | ---------------------------------------------- |
-| **Core** | Electron, React 19, TypeScript |
-| **Build** | Vite, Electron Forge |
-| **Estilos** | Tailwind CSS v4, Radix UI, Lucide Icons |
-| **Estado** | TanStack Query, TanStack Router |
-| **Backend** | NestJS (gateway interno), ORPC (RPC type-safe) |
-| **Base de Datos** | Better-SQLite3, Drizzle ORM |
-| **Gráficos** | Nivo (Line, Bar, Pie) |
-| **Testing** | Vitest, Playwright |
-
----
-
-## 💻 Desarrollo
-
-```bash
-# Iniciar entorno de dev (Electron + Vite HMR)
-npm start
-
-# Ejecutar linting
-npm run lint
-
-# Verificación de tipos
-npm run type-check
-
-# Formatear código
-npm run format:write
-
-# Ejecutar pruebas
-npm test
+```text
+API Base URL: http://localhost:8045/v1 (por defecto, configurable en la página Proxy; los builds de desarrollo usan 8046)
+API Key: (cópiala de la página Proxy de la app)
+Model: gemini-3-flash (o cualquier modelo mapeado)
```
----
+> [!WARNING]
+> Los builds no están firmados. Si Windows muestra "Windows protegió su PC", haz clic en **Más información → Ejecutar de todas formas**.
-## ❓ Preguntas Frecuentes
+No hay `.env.example` y ninguna variable es obligatoria. Variables opcionales que lee el código o que describen los docs:
+
+| Variable | Obligatoria | Descripción |
+|---|---|---|
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | No | Envía las peticiones salientes de la app por un proxy local (ver inspección TLS en [Modelo de seguridad](#modelo-de-seguridad)). |
+| `NODE_EXTRA_CA_CERTS` | No | Certificado de CA adicional para el TLS del lado Node al inspeccionar tráfico. |
+| `SENTRY_DSN` | No | DSN de Sentry usado cuando el envío de errores está activado. |
+
+## 🛠️ Stack
+
+| Capa | Tecnología |
+|---|---|
+| Shell de escritorio | Electron 41, Electron Forge, Vite |
+| Interfaz | React 19, TypeScript, Tailwind CSS 4, Radix UI, gráficos Nivo, i18next |
+| Flujo de datos de la app | TanStack Router y Query, oRPC sobre IPC de Electron |
+| Proxy | NestJS 11 sobre Fastify |
+| Almacenamiento | SQLite (better-sqlite3 + Drizzle ORM), llavero del sistema vía `keytar` |
+| Logs y errores | Winston (archivos rotativos), Sentry (opcional) |
+| Pruebas | Vitest, Playwright |
+
+## Arquitectura
+
+```mermaid
+flowchart LR
+ C["Cliente: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["Proxy NestJS, puerto 8045"]
+ P --> S["Planificador de cuentas y circuit breaker"]
+ S -->|"cuenta Google OAuth"| G["APIs upstream de Google"]
+ M["CloudMonitor y AutoSwitch, cuota cada 5 min"] -->|"consulta de cuota"| G
+ S -->|"lee cuentas"| DB[("SQLite: better-sqlite3 y Drizzle")]
+ M --> DB
+ K["AES-256-GCM, clave maestra en el llavero del sistema"] -->|"cifra tokens"| DB
+```
+
+1. Un cliente envía peticiones en formato OpenAI o Anthropic al proxy NestJS (Fastify, escuchando en `0.0.0.0`).
+2. El guard del proxy comprueba la API key cuando hay una configurada; con la clave vacía el proxy funciona en modo abierto.
+3. El token manager elige una cuenta según el modo de planificación y el estado del circuit breaker de cada cuenta, y llama a las APIs upstream de Google con el token OAuth de esa cuenta.
+4. `CloudMonitorService` consulta la cuota cada 5 minutos y `AutoSwitchService` cambia la cuenta activa cuando la cuota está por debajo del 5 % o la cuenta sufre rate limit.
+5. El renderer React 19 (TanStack Router y Query) habla con el proceso principal mediante oRPC sobre IPC; cuentas, uso y ajustes viven en SQLite (better-sqlite3 + Drizzle). Notas de diseño: [`docs/cloud_features.md`](docs/cloud_features.md).
+
+## Modelo de seguridad
+
+Gemini Nexus guarda tokens OAuth de varias cuentas y reenvía tráfico hacia arriba, así que el manejo de credenciales es el núcleo del diseño. Todo lo de abajo está implementado en este repositorio; los límites se indican donde existen.
+
+- **Almacenamiento y aislamiento de credenciales.** `token_json` y `quota_json` se cifran con AES-256-GCM (IV único por operación, autenticado) antes de llegar a SQLite. La clave maestra vive en el almacén de credenciales del sistema vía `keytar` (Administrador de credenciales de Windows, Keychain de macOS, Secret Service/libsecret en Linux), nunca en un archivo plano. Las filas heredadas en texto plano se migran al arrancar. Las cuentas se guardan en su propia base de datos (`cloud_accounts.db`), independiente de la base local del IDE.
+- **Enmascarado de logs.** Claves como `token`, `refresh_token`, `api_key`, `authorization`, `cookie` y `client_secret` se sustituyen por `[REDACTED]` antes de registrarse ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); el logger de tráfico también oculta las cabeceras `authorization`, `x-api-key` y `cookie`.
+- **Registro de peticiones, no pista de auditoría.** Winston escribe logs de API, tráfico y app en archivos rotativos (log de API: 30 días, 50 MB por archivo). Son logs operativos, no una pista de auditoría a prueba de manipulación; los archivos `*-audit.json` son el control de rotación de `winston-daily-rotate-file`.
+- **Acceso al proxy.** El proxy viene apagado. Una vez activado escucha en `0.0.0.0`, y las peticiones solo se autentican cuando `api_key` no está vacía (vacía significa modo abierto). Define una clave y mantenla privada.
+- **Inspección TLS (solo para depurar).** [`docs/proxyman-install.md`](docs/proxyman-install.md) y [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explican cómo leer el tráfico HTTPS de la app con Proxyman: confiar en su CA raíz, definir las variables de proxy y `NODE_EXTRA_CA_CERTS` y después iniciar la app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (y el flag `-AllowInsecureTls` del script) es un ajuste temporal; nunca lo dejes activado. No hagas commit de direcciones de proxy, rutas de certificados, cookies ni códigos OAuth, y oculta datos de los logs antes de compartirlos. `scripts/start-antigravity-with-proxyman.ps1` apunta al cliente oficial de Antigravity instalado, no a esta app.
+- **Envío de errores.** Los informes de Sentry (necesitan `SENTRY_DSN`) dependen del ajuste `error_reporting_enabled`, que `DEFAULT_APP_CONFIG` trae como `true`; desactívalo en Settings para no enviarlos. El segmento con el nombre de usuario de Windows se enmascara en los mensajes de excepción enviados.
+
+Versiones soportadas y cómo reportar una vulnerabilidad: [`SECURITY.md`](SECURITY.md).
+
+## 💻 Documentación y desarrollo
+
+- [`docs/cloud_features.md`](docs/cloud_features.md): diseño del pool de cuentas, la monitorización de cuota y el cambio automático.
+- [`docs/proxyman-install.md`](docs/proxyman-install.md) y [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): configuración de la inspección TLS (Windows).
+- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): integración con endpoint personalizado de OpenCode (en portugués).
+- [`cli/README.md`](cli/README.md): la herramienta de línea de comandos en Python.
+- [`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).
+- Traducciones: [English](README.md), [Português](README.pt-BR.md), [中文](README.zh-CN.md).
+
+### Estructura
+
+```text
+src/
+├── components/ # UI (proxy/, usage/, primitivas ui/)
+├── ipc/ # routers oRPC (account, cloud, config, gateway, usage...)
+├── server/ # gateway proxy NestJS (módulos: proxy, usage)
+├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
+├── routes/ # index, usage, proxy, settings
+├── utils/ # paths, logger, sensitiveDataMasking
+└── tests/ # pruebas unitarias (Vitest) y E2E (Playwright)
+cli/ # CLI de Python aparte para cambiar de cuenta y consultar cuota
+docs/ # notas de diseño y guías de Proxyman
+scripts/ # setup-dev, build-windows, generate-assets
+```
+
+### Scripts
+
+| Comando | Qué hace |
+|---|---|
+| `pnpm start` | Ejecuta la app en modo dev (`electron-forge start`, con `DEBUG=electron-forge:*`). |
+| `pnpm run dev` | Igual que `start`. |
+| `pnpm run package` | Empaqueta la app con Electron Forge, sin generar instaladores. |
+| `pnpm run make` | Genera instaladores/paquetes para la plataforma actual. |
+| `pnpm run make:win` | Helper de build en Windows: extrae WiX de `wix314-binaries.zip`, lo añade al `PATH` y ejecuta `electron-forge make`. |
+| `pnpm run publish` | Publica mediante Electron Forge. |
+| `pnpm run setup` | Ejecuta `scripts/setup-dev.js`: detecta la toolchain nativa e instala o guía la configuración. |
+| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; se ejecuta solo tras `pnpm install`. |
+| `pnpm run lint` | ESLint sobre el repositorio. |
+| `pnpm run format` | Comprobación de Prettier. |
+| `pnpm run format:write` | Prettier con escritura. |
+| `pnpm test` | Pruebas unitarias Vitest (`vitest run`). |
+| `pnpm run test:watch` | Vitest en modo watch. |
+| `pnpm run test:unit` | Vitest (modo por defecto). |
+| `pnpm run test:e2e` | Pruebas E2E con Playwright. |
+| `pnpm run test:all` | Pruebas unitarias y después Playwright. |
+| `pnpm run type-check` | `tsc --noEmit`. |
+
+## ❓ Preguntas frecuentes
-P: ¿Aviso de Windows SmartScreen ("Windows protegió su PC") durante la instalación?
+Windows muestra "Windows protegió su PC". ¿Es normal?
+
+Sí. Los builds no están firmados. Haz clic en **Más información → Ejecutar de todas formas**.
-Sí, este es un aviso común para nuevas aplicaciones no firmadas. Haz clic en **"Más información"** y luego en **"Ejecutar de todas formas"**. Consulta la advertencia en la parte superior del README para más detalles.
-P: ¿La app no inicia al compilar desde el código fuente?
+Mi IDE no llega al proxy.
+
+El proxy viene apagado: actívalo en la página Proxy. El puerto por defecto es `8045` (`8046` en builds de desarrollo) y se puede cambiar allí. Copia la API key de esa misma página y comprueba que haya al menos una cuenta en el pool.
-1. Asegúrate de que todas las dependencias están instaladas: `npm install`.
-2. Verifica que tu versión de Node.js sea >= 20.
-3. Intenta eliminar `node_modules` y reinstalar.
-4. En Windows, asegúrate de que el WiX Toolset esté disponible para el comando `npm run make`.
-P: ¿El inicio de sesión de la cuenta falló?
+¿Necesito una API key?
+
+Con `api_key` vacía el proxy funciona en modo abierto. Una vez activado escucha en `0.0.0.0`, así que define una clave y mantenla privada.
-1. Asegúrate de que tu conexión a la red funcione correctamente.
-2. Intenta borrar los datos de la app y volver a iniciar sesión.
-3. Comprueba si la cuenta está restringida por Google/Claude.
-P: ¿El IDE no se puede conectar al proxy?
+¿Puedo usar modelos Claude?
+
+Sí, mediante el mapeo de modelos sobre las cuentas de Google del pool, no con cuentas de Claude separadas.
-1. Asegúrate de que el proxy esté funcionando (indicador verde en la barra de estado).
-2. Confirma que el puerto coincide con tu configuración del IDE (por defecto `10100`).
-3. Copia la API key directamente desde la página Proxy y pégala en la configuración de tu IDE.
-4. Asegúrate de tener al menos una cuenta activa en la página Cuentas.
----
+
+¿Dónde se guardan mis tokens?
+
+En un `cloud_accounts.db` aparte, con `token_json` y `quota_json` cifrados con AES-256-GCM. La clave maestra vive en el almacén de credenciales del sistema vía `keytar`. Detalles en [Modelo de seguridad](#modelo-de-seguridad).
+
+
+
+
+¿Puedo usarlo comercialmente?
+
+Revisa antes la [Licencia](#-licencia): el código heredado de AntigravityManager es CC BY-NC-SA 4.0 (no comercial) y el código nuevo es MIT.
+
+
+
+## Limitaciones y próximos pasos
+
+- El acceso upstream pasa por los endpoints `v1internal` de Cloud Code de Google y por scopes OAuth ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). Son APIs internas, sin documentar, que pueden cambiar sin aviso. El proyecto no es oficial y no está afiliado a Google ni a Anthropic.
+- Las cuentas se añaden por Google OAuth; a los modelos Claude se llega mediante el mapeo de modelos, no con cuentas de Claude separadas.
+- Las pruebas end-to-end no se ejecutan en CI (Electron necesita un entorno gráfico); ejecuta `pnpm run test:e2e` en local.
+- El MSI de Windows solo se genera cuando el WiX Toolset está disponible en la máquina de build; si no, el artefacto de Windows es el ZIP.
+- Los workflows de `.github/workflows/` están escritos para GitHub (llaman al CLI `gh` y al publicador de releases de GitHub), por eso este README no muestra badge de CI.
+- Próximo paso declarado por el proyecto: migrar el código original restante a MIT (ver la [Licencia](#-licencia)).
## 🤝 Contribuir
-¡Las contribuciones son bienvenidas! Por favor lee `CONTRIBUTING.md` para más detalles.
+Lee [`CONTRIBUTING.md`](CONTRIBUTING.md) y [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Las versiones las genera semantic-release a partir de Conventional Commits. Antes de abrir un PR, esto tiene que pasar:
----
+```bash
+pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
+```
## 📄 Licencia
-Este proyecto utiliza una estructura de licencia dual:
-
-- **Código original** de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) por [Draculabo](https://github.com/Draculabo): Licenciado bajo [CC BY-NC-SA 4.0](LICENSE).
-- **Todo el código nuevo, funcionalidades y arquitectura** por [evandrodevbr](https://github.com/evandrodevbr): Licenciado bajo la [Licencia MIT](LICENSE-MIT).
-
-> 🔄 **Aviso de Migración:** Este proyecto está siendo migrado activamente a una licencia completamente open-source (MIT). A medida que el código original restante se reescribe progresivamente, todo el proyecto hará la transición a MIT. Estamos comprometidos a hacer Gemini Nexus 100% open-source.
+Licencia mixta: el código heredado de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (de Draculabo) es [CC BY-NC-SA 4.0](LICENSE) (no comercial, compartir igual); todo el código nuevo es [MIT](LICENSE-MIT). El proyecto está migrando a MIT a medida que se reescribe el código original restante, así que revisa ambos archivos antes de cualquier uso comercial.
---
-## 🙏 Créditos
+
-Este proyecto fue originalmente un fork de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) creado por [Draculabo](https://github.com/Draculabo). El concepto inicial del proxy y la estructura base de Electron se basaron en su trabajo.
+
-Desde el fork, **la gran mayoría del código ha sido reescrito, rediseñado y expandido** por [evandrodevbr](https://github.com/evandrodevbr), incluyendo pero no limitado a:
+
-- Rediseño completo de UI/UX (navegación, cuentas, analíticas de uso, gestión del proxy)
-- Dashboard de Analíticas de Uso con seguimiento de costos, promedios de tokens e integración con OpenRouter
-- Monitor de tráfico con inspección de tokens/costos por solicitud
-- Aislamiento de entorno (dev/prod), pipeline CI/CD e infraestructura de pruebas
-- Configuración rápida para IDEs (OpenCode, Cursor, VS Code, Claude Code)
-- Configuración personalizada de precios de modelos
-- Toda la documentación e internacionalización (EN, PT-BR, ES, ZH-CN)
+
-
-
-## 📌 The problem
-
-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.
-
-## ✨ What it does
-
-- **Pools** Google accounts added through OAuth, with status (Active, Rate Limited, Expired), last-used time and an optional per-account proxy URL.
-- **Switches** accounts automatically when quota drops below 5 % or an account is rate-limited; `CloudMonitorService` polls quota every 5 minutes.
-- **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).
-- **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.
-- **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)).
-
## 🖼️ Demo
+
@@ -51,20 +28,38 @@ Working with AI-powered IDEs and coding tools on a single Google account means q
+## ✨ What it does
+
+Working with AI-powered IDEs on a single Google account means quota that runs out, manual account switching and no view of what the proxy sends upstream. Gemini Nexus keeps every account in one pool and serves them through one local endpoint.
+
+
+
+
One local endpoint 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. Model names are mapped through custom_mapping and anthropic_mapping.
+
Account pool Google accounts added through OAuth, each with its status (Active, Rate Limited, Expired), last-used time and an optional per-account proxy URL.
+
+
+
Auto-switch CloudMonitorService polls quota every 5 minutes and AutoSwitchService moves to another account when quota drops below 5 % or the account is rate-limited.
+
Scheduling with a circuit breaker cache-first, balance (default) or performance-first, with a per-account circuit breaker (default backoff 60 s → 5 min → 30 min → 2 h).
+
+
+
Usage and cost Token usage per account and model, prompt and completion charts, and cost estimates from editable per-model pricing.
+
Traffic inspector Latency, status and model for each request, replay of logged requests, generated cURL and Python snippets, plus an IDE Quick Setup.
+
+
+
+Stored credentials are encrypted with AES-256-GCM under an OS-keychain master key (see [Security model](#-security-model)).
+
+## How it works
+
+1. **Add accounts.** Sign in with Google OAuth on the Accounts page. Tokens are encrypted before they reach SQLite.
+2. **Point your IDE at the proxy.** Enable the proxy on the Proxy page (it is off by default) and use `http://localhost:8045/v1` with the API key shown there, in OpenAI or Anthropic format.
+3. **Nexus routes each request.** The token manager picks an account by scheduling mode and circuit-breaker state, calls Google's upstream APIs with that account's OAuth token, and auto-switch moves on when quota drops below 5 % or an account is rate-limited.
+
+The full flow, with the components involved, is in [Architecture](#-architecture).
+
## 🚀 Quickstart
-**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:
-
-```text
-API Base URL: http://localhost:8045/v1 (default, configurable on the Proxy page; development builds use 8046)
-API Key: (copy it from the Proxy page in the app)
-Model: gemini-3-flash (or any mapped model)
-```
-
-> [!WARNING]
-> Builds are not code-signed. If Windows shows "Windows protected your PC", click **More info → Run anyway**.
-
-**Build from source.**
+There are no prebuilt downloads on the [Gitea Releases](https://git.evandro.dev.br/evandro/gemini-nexus/releases) page yet (the release workflows in `.github/workflows/` target GitHub), so build from source.
| Tool | Minimum version |
|---|---|
@@ -81,6 +76,17 @@ pnpm run make # installers/packages for the current platform
pnpm run make:win # Windows: extracts WiX from wix314-binaries.zip, then runs make
```
+Then add at least one account, enable the proxy (it is disabled by default) and point your IDE at it:
+
+```text
+API Base URL: http://localhost:8045/v1 (default, configurable on the Proxy page; development builds use 8046)
+API Key: (copy it from the Proxy page in the app)
+Model: gemini-3-flash (or any mapped model)
+```
+
+> [!WARNING]
+> Builds are not code-signed. If Windows shows "Windows protected your PC", click **More info → Run anyway**.
+
There is no `.env.example` and no variable is required. Optional variables read by the code or described in the docs:
| Variable | Required | Description |
@@ -89,6 +95,18 @@ There is no `.env.example` and no variable is required. Optional variables read
| `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. |
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Desktop shell | Electron 41, Electron Forge, Vite |
+| Interface | React 19, TypeScript, Tailwind CSS 4, Radix UI, Nivo charts, i18next |
+| App data flow | TanStack Router and Query, oRPC over Electron IPC |
+| Proxy | NestJS 11 on Fastify |
+| Storage | SQLite (better-sqlite3 + Drizzle ORM), OS keychain via `keytar` |
+| Logs and errors | Winston (rotating files), Sentry (optional) |
+| Tests | Vitest, Playwright |
+
## 🧱 Architecture
```mermaid
@@ -121,7 +139,16 @@ Gemini Nexus holds OAuth tokens for several accounts and forwards traffic upstre
Supported versions and how to report a vulnerability: [`SECURITY.md`](SECURITY.md).
-## 🗂️ Structure
+## 📚 Documentation
+
+- [`docs/cloud_features.md`](docs/cloud_features.md): account pool, quota monitoring and auto-switch design.
+- [`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).
+
+### 🗂️ Structure
```text
src/
@@ -137,7 +164,7 @@ docs/ # design notes and Proxyman guides
scripts/ # setup-dev, build-windows, generate-assets
```
-## 🧪 Scripts
+### 🧪 Scripts
| Command | What it does |
|---|---|
@@ -159,14 +186,49 @@ scripts/ # setup-dev, build-windows, generate-assets
| `pnpm run test:all` | Unit tests, then Playwright. |
| `pnpm run type-check` | `tsc --noEmit`. |
-## 📚 Documentation
+## FAQ
-- [`docs/cloud_features.md`](docs/cloud_features.md): account pool, quota monitoring and auto-switch design.
-- [`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).
+
+Windows shows "Windows protected your PC". Is that expected?
+
+Yes. Builds are not code-signed. Click **More info → Run anyway**.
+
+
+
+
+My IDE cannot reach the proxy.
+
+The proxy is disabled by default: enable it on the Proxy page. The default port is `8045` (`8046` in development builds) and can be changed there. Copy the API key from the same page and make sure at least one account is in the pool.
+
+
+
+
+Do I need an API key?
+
+With an empty `api_key` the proxy runs in open mode. Once enabled it listens on `0.0.0.0`, so set a key and keep it private.
+
+
+
+
+Can I use Claude models?
+
+Yes, through model mapping on the Google accounts in the pool, not through separate Claude accounts.
+
+
+
+
+Where are my tokens stored?
+
+In a separate `cloud_accounts.db`, with `token_json` and `quota_json` encrypted by AES-256-GCM. The master key lives in the OS credential store through `keytar`. Details in [Security model](#-security-model).
+
+
+
+
+Can I use it commercially?
+
+Check the [License](#-license) first: code inherited from AntigravityManager is CC BY-NC-SA 4.0 (non-commercial), new code is MIT.
+
+
## 🛣️ Limitations and next steps
@@ -188,3 +250,13 @@ pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
## 📄 License
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.
+
+---
+
+
+English · Português · 中文 · Español
-> [!IMPORTANT]
-> **Usuários do Windows:** Se você vir um aviso do SmartScreen **"O Windows protegeu o seu computador"** durante a instalação, clique em **"Mais informações"** e depois em **"Executar mesmo assim"**. Isso é um aviso de segurança esperado para aplicativos novos e não assinados.
-
----
-
-## 📖 Sumário
-
-- [✨ Por que o Gemini Nexus?](#-por-que-o-gemini-nexus)
-- [🎯 Funcionalidades](#-funcionalidades)
-- [📸 Screenshots](#-screenshots)
-- [⚡ Instalação e Início Rápido](#-instalação-e-início-rápido)
-- [🛠️ Stack Tecnológica](#️-stack-tecnológica)
-- [💻 Desenvolvimento](#-desenvolvimento)
-- [❓ FAQ](#-faq)
-- [🤝 Contribuindo](#-contribuindo)
-- [📄 Licença](#-licença)
-
----
-
-## ✨ Por que o Gemini Nexus?
-
-Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes problemas?
-
-- 😫 **Limites de cota:** A cota da conta única acaba rápido, exigindo trocas manuais frequentes.
-- 🔄 **Gestão de contas:** Gerenciar múltiplas contas do Google/Claude é cansativo.
-- 📊 **Uso às cegas:** Você não sabe quantos tokens já consumiu ou quanta cota resta.
-- 🔌 **Problemas de integração:** Precisa de um proxy local confiável que fale os protocolos OpenAI/Anthropic nativamente.
-- 🔍 **Falta de transparência:** Não consegue ver o que está sendo enviado ou recebido pelo proxy nos bastidores.
-
-O **Gemini Nexus** resolve tudo isso. É um aplicativo desktop profissional em Electron que funciona como um gateway inteligente entre suas ferramentas de desenvolvimento e o Google Gemini / Claude AI.
-
-### Principais Vantagens
-
-- ✅ **Pool de Contas Ilimitado** — Adicione quantas contas Google Gemini & Claude quiser.
-- ✅ **Troca Automática Inteligente** — Rotaciona automaticamente para a próxima conta disponível quando a cota está baixa ou com rate limit.
-- ✅ **Analytics de Uso em Tempo Real** — Dashboard nível SaaS com gráficos de área, indicadores de tendência e distribuição por modelo.
-- ✅ **Observabilidade Completa do Proxy** — Monitor de tráfego ao vivo, replay de requisições e inspetor de capacidades dos modelos.
-- ✅ **Compatível com OpenAI & Anthropic** — Proxy drop-in para Cursor, Windsurf, OpenCode e qualquer ferramenta compatível com OpenAI.
-- ✅ **Seguro por Padrão** — Criptografia AES-256-GCM com gerenciamento nativo de credenciais do sistema operacional.
-
----
-
-## 🎯 Funcionalidades
-
-
-
-
-
☁️ Pool de Contas na Nuvem
-
-
Adicione contas ilimitadas do Google Gemini / Claude via OAuth
-
Exibe avatar, e-mail, status e último uso
-
Monitoramento de status em tempo real (Ativa, Rate Limited, Expirada)
-
Configuração de proxy URL por conta
-
Gerenciamento de perfil de identidade do dispositivo com histórico
-
-
-
-
📊 Dashboard de Analytics de Uso
-
-
Consumo de tokens em tempo real com auto-refresh a cada 15s
-
Gráficos de área para tokens de prompt & completion (diário/horário)
-
Indicadores de tendência (% de variação vs período anterior)
-
Sparklines inline nos cards de estatísticas
-
Ranking de distribuição por modelo com gráficos de barras horizontais
-
Visualização da proporção Prompt/Completion
-
-
-
-
-
-
🔌 Proxy de API Local (Gateway)
-
-
Endpoint compatível com OpenAI /v1/chat/completions
-
Endpoint compatível com Anthropic /v1/messages
-
Streaming SSE completo (testado com Cursor, Windsurf, OpenCode)
-
Mapeamento de modelos (ex: claude-sonnet-4-6 → gemini-3-flash)
-
Porta, timeout e API key configuráveis
-
Controle de visibilidade de modelos
-
-
-
-
🔄 Troca Automática Inteligente
-
-
Modo de pool ilimitado com seleção inteligente de backup
-
Troca automática quando cota < 5% ou com rate limit
-
Monitoramento em segundo plano a cada 5 minutos
-
Fallback gracioso com rastreamento de motivo do status
-
-
-
-
-
-
🔍 Observabilidade do Proxy (Avançado)
-
-
Monitor de Tráfego — Log ao vivo de requisições/respostas com latência e informações do modelo
-
Replay de Requisições — Reproduza qualquer requisição registrada para debugging
-
Capacidades dos Modelos — Inspecione suporte a visão, thinking, streaming e modo JSON
-
Ferramentas para Devs — Geração de código cURL & Python, cópia com um clique
-
-
-
-
🔐 Segurança e Criptografia
-
-
Criptografia AES-256-GCM para todos os dados sensíveis
-
Integração com gerenciador de credenciais nativo (Keytar + SafeStorage)
-
Migração automática de dados legados em texto plano
-
Armazenamento criptografado de tokens & cotas por conta
-
-
-
-
-
-
⚙️ Configurações e Personalização
-
-
Suporte a temas Escuro / Claro / Sistema
-
Multi-idioma: English & Português (Brasil)
-
Override de proxy URL por conta
-
Toggles de visibilidade de modelos
-
Acesso ao diretório de logs
-
-
-
-
🖥️ Experiência Desktop
-
-
App nativo Electron com integração na bandeja do sistema
-
Sidebar retrátil com estado persistente
-
Layouts responsivos em todas as telas
-
Barra de status com indicadores ao vivo de proxy e conexão
-
Error boundaries com fallbacks amigáveis ao usuário
-
-
-
-
-
----
+
## 📸 Screenshots
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
----
+
+Mais screenshots: uso, proxy, roteamento, docs, conexões, configurações
-## ⚡ Instalação e Início Rápido
+
+
+
+
+
+
-### 📦 Download
+
-Você pode baixar os binários pré-compilados mais recentes para Windows, macOS e Linux na nossa [página de Releases](https://github.com/evandrodevbr/GeminiNexus/releases).
+## 🎯 Funcionalidades
-*(Consulte o aviso no topo desta página se você estiver usando o Windows e encontrar o prompt do SmartScreen).*
+Usar IDEs com IA numa única conta Google significa cota que acaba, troca manual de conta e nenhuma visão do que o proxy manda para cima. O Gemini Nexus mantém todas as contas num pool e as serve por um único endpoint local.
-### 🔌 Usando com IDEs de IA
+
+
+
Um endpoint local POST /v1/chat/completions (OpenAI), POST /v1/messages (Anthropic), GET /v1/models e GET /v1/models/capabilities, para que Cursor, Windsurf, OpenCode, Claude Code e clientes parecidos se conectem. Os nomes de modelo são mapeados por custom_mapping e anthropic_mapping.
+
Pool de contas Contas Google adicionadas via OAuth, cada uma com status (Active, Rate Limited, Expired), horário do último uso e uma URL de proxy opcional por conta.
+
+
+
Troca automática O CloudMonitorService consulta a cota a cada 5 minutos e o AutoSwitchService passa para outra conta quando a cota cai abaixo de 5 % ou a conta sofre rate limit.
+
Agendamento com circuit breaker cache-first, balance (padrão) ou performance-first, com circuit breaker por conta (backoff padrão 60 s → 5 min → 30 min → 2 h).
+
+
+
Uso e custo Consumo de tokens por conta e por modelo, gráficos de prompt e completion e estimativa de custo com preço por modelo editável.
+
Inspetor de tráfego Latência, status e modelo de cada requisição, replay de requisições registradas, snippets cURL e Python gerados e um Quick Setup para IDEs.
+
+
-Com o aplicativo rodando e pelo menos uma conta adicionada, configure sua IDE preferida (Cursor, Windsurf, OpenCode, etc.):
+As credenciais salvas são criptografadas com AES-256-GCM sob uma chave mestra guardada no chaveiro do sistema (veja [Modelo de segurança](#modelo-de-segurança)).
-```plaintext
-API Base URL: http://localhost:10100/v1
+## Como funciona
+
+1. **Adicione contas.** Entre com Google OAuth na página Accounts. Os tokens são criptografados antes de chegar ao SQLite.
+2. **Aponte a IDE para o proxy.** Ative o proxy na página Proxy (ele vem desligado) e use `http://localhost:8045/v1` com a API key mostrada ali, no formato OpenAI ou Anthropic.
+3. **O Nexus roteia cada requisição.** O token manager escolhe uma conta pelo modo de agendamento e pelo estado do circuit breaker, chama as APIs upstream do Google com o token OAuth dessa conta, e a troca automática entra em ação quando a cota cai abaixo de 5 % ou uma conta sofre rate limit.
+
+O fluxo completo, com os componentes envolvidos, está em [Arquitetura](#arquitetura).
+
+## ⚡ Início rápido
+
+Ainda não há downloads prontos na página de [Releases do Gitea](https://git.evandro.dev.br/evandro/gemini-nexus/releases) (os workflows de release em `.github/workflows/` são para o GitHub), então compile pelo código-fonte.
+
+| Ferramenta | Versão mínima |
+|---|---|
+| Node.js | 20+ (recomendado no `AGENTS.md`; o `.nvmrc` fixa 22.17.1) |
+| pnpm | 10.11.0 (`packageManager`; o lockfile é `pnpm-lock.yaml`) |
+| Toolchain nativa | exigida por `better-sqlite3` e `keytar`: Visual Studio 2022 Build Tools (C++) no Windows, Xcode Command Line Tools no macOS, `build-essential` + `python3` + `libsecret-1-dev` no Ubuntu (`base-devel` + `python` + `libsecret` no Arch) |
+
+```bash
+git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
+cd gemini-nexus
+pnpm install # o postinstall roda scripts/setup-dev.js --check-only para conferir a toolchain
+pnpm start # modo dev (Electron + Vite HMR)
+pnpm run make # instaladores/pacotes para a plataforma atual
+pnpm run make:win # Windows: extrai o WiX de wix314-binaries.zip e roda o make
+```
+
+Depois adicione pelo menos uma conta, ative o proxy (ele vem desligado) e aponte sua IDE para ele:
+
+```text
+API Base URL: http://localhost:8045/v1 (padrão, configurável na página Proxy; builds de desenvolvimento usam 8046)
API Key: (copie da página Proxy no app)
-Model: gemini-3-flash (ou qualquer modelo mapeado)
+Model: gemini-3-flash (ou qualquer modelo mapeado)
```
-### 🛠️ Compilando pelo Código Fonte
+> [!WARNING]
+> Os builds não são assinados. Se o Windows mostrar "O Windows protegeu o seu computador", clique em **Mais informações → Executar mesmo assim**.
-#### Pré-requisitos
+Não existe `.env.example` e nenhuma variável é obrigatória. Variáveis opcionais lidas pelo código ou descritas nos docs:
-- **Node.js** v20 ou superior
-- **npm** (este projeto usa `package-lock.json`)
+| Variável | Obrigatória | Descrição |
+|---|---|---|
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Não | Encaminha as requisições de saída do app por um proxy local (veja inspeção TLS em [Modelo de segurança](#modelo-de-segurança)). |
+| `NODE_EXTRA_CA_CERTS` | Não | Certificado de CA extra para o TLS do lado Node ao inspecionar tráfego. |
+| `SENTRY_DSN` | Não | DSN do Sentry usado quando o envio de erros está ativo. |
-#### Passos
+## 🛠️ Stack
-```bash
-# Clone o repositório
-git clone https://github.com/evandrodevbr/GeminiNexus.git
-cd GeminiNexus
+| Camada | Tecnologia |
+|---|---|
+| Shell desktop | Electron 41, Electron Forge, Vite |
+| Interface | React 19, TypeScript, Tailwind CSS 4, Radix UI, gráficos Nivo, i18next |
+| Fluxo de dados do app | TanStack Router e Query, oRPC sobre IPC do Electron |
+| Proxy | NestJS 11 sobre Fastify |
+| Armazenamento | SQLite (better-sqlite3 + Drizzle ORM), chaveiro do sistema via `keytar` |
+| Logs e erros | Winston (arquivos rotativos), Sentry (opcional) |
+| Testes | Vitest, Playwright |
-# Instale as dependências
-npm install
+## Arquitetura
-# Inicie o modo de desenvolvimento
-npm start
-
-# Compile para produção (ex: instalador Windows)
-npm run make
+```mermaid
+flowchart LR
+ C["Cliente: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["Proxy NestJS, porta 8045"]
+ P --> S["Agendador de contas e circuit breaker"]
+ S -->|"conta Google OAuth"| G["APIs upstream do Google"]
+ M["CloudMonitor e AutoSwitch, cota a cada 5 min"] -->|"consulta de cota"| G
+ S -->|"lê contas"| DB[("SQLite: better-sqlite3 e Drizzle")]
+ M --> DB
+ K["AES-256-GCM, chave mestra no chaveiro do sistema"] -->|"criptografa tokens"| DB
```
----
+1. Um cliente envia requisições no formato OpenAI ou Anthropic para o proxy NestJS (Fastify, escutando em `0.0.0.0`).
+2. O guard do proxy confere a API key quando há uma configurada; com a chave vazia o proxy roda em modo aberto.
+3. O token manager escolhe uma conta segundo o modo de agendamento e o estado do circuit breaker de cada conta, e chama as APIs upstream do Google com o token OAuth dessa conta.
+4. O `CloudMonitorService` consulta a cota a cada 5 minutos e o `AutoSwitchService` troca a conta ativa quando a cota está abaixo de 5 % ou a conta sofre rate limit.
+5. O renderer React 19 (TanStack Router e Query) conversa com o processo principal via oRPC sobre IPC; contas, uso e configurações ficam no SQLite (better-sqlite3 + Drizzle). Notas de design: [`docs/cloud_features.md`](docs/cloud_features.md).
-## 🛠️ Stack Tecnológica
+## Modelo de segurança
-| Categoria | Tecnologias |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| **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/) |
-| **Estilização** | [Tailwind CSS v4](https://tailwindcss.com/), [Radix UI](https://www.radix-ui.com/), [Lucide Icons](https://lucide.dev/) |
-| **Estado** | [TanStack Query](https://tanstack.com/query/latest), [TanStack Router](https://tanstack.com/router/latest) |
-| **Backend** | [NestJS](https://nestjs.com/) (gateway interno), [ORPC](https://orpc.unnoq.com/) (RPC type-safe) |
-| **Banco de Dados** | [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3), [Drizzle ORM](https://orm.drizzle.team/) |
-| **Gráficos** | [Nivo](https://nivo.rocks/) (Line, Bar, Pie) |
-| **i18n** | [react-i18next](https://react.i18next.com/) |
-| **Testes** | [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/) |
+O Gemini Nexus guarda tokens OAuth de várias contas e repassa tráfego para cima, então o tratamento de credenciais é o centro do design. Tudo abaixo está implementado neste repositório; os limites aparecem onde existem.
----
+- **Armazenamento e isolamento de credenciais.** `token_json` e `quota_json` são criptografados com AES-256-GCM (IV único por operação, autenticado) antes de chegar ao SQLite. A chave mestra fica no cofre de credenciais do sistema via `keytar` (Gerenciador de Credenciais do Windows, Keychain do macOS, Secret Service/libsecret no Linux), nunca num arquivo comum. Linhas legadas em texto puro são migradas na inicialização. As contas ficam num banco próprio (`cloud_accounts.db`), separado do banco local da IDE.
+- **Mascaramento de logs.** Chaves como `token`, `refresh_token`, `api_key`, `authorization`, `cookie` e `client_secret` são trocadas por `[REDACTED]` antes de ir para o log ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); o logger de tráfego também oculta os headers `authorization`, `x-api-key` e `cookie`.
+- **Log de requisições, não trilha de auditoria.** O Winston grava logs de API, tráfego e app em arquivos rotativos (log de API: 30 dias, 50 MB por arquivo). São logs operacionais, não uma trilha de auditoria à prova de adulteração; os arquivos `*-audit.json` são o controle de rotação do `winston-daily-rotate-file`.
+- **Acesso ao proxy.** O proxy vem desligado. Quando ativado, escuta em `0.0.0.0`, e as requisições só são autenticadas quando `api_key` não está vazia (vazia significa modo aberto). Defina uma chave e mantenha-a privada.
+- **Inspeção TLS (só para debug).** [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explicam como ler o tráfego HTTPS do app com o Proxyman: confiar na CA raiz dele, definir as variáveis de proxy e `NODE_EXTRA_CA_CERTS` e então iniciar o app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (e a flag `-AllowInsecureTls` do script) é um ajuste temporário; nunca deixe ligado. Não faça commit de endereços de proxy, caminhos de certificado, cookies ou códigos OAuth, e oculte dados dos logs antes de compartilhá-los. `scripts/start-antigravity-with-proxyman.ps1` mira o cliente oficial do Antigravity instalado, não este app.
+- **Envio de erros.** Os relatórios do Sentry (precisam de `SENTRY_DSN`) dependem da configuração `error_reporting_enabled`, que o `DEFAULT_APP_CONFIG` traz como `true`; desative em Settings para não enviar. O trecho com o nome de usuário do Windows é mascarado nas mensagens de exceção enviadas.
-## 💻 Desenvolvimento
+Versões suportadas e como reportar uma vulnerabilidade: [`SECURITY.md`](SECURITY.md).
-```bash
-# Iniciar ambiente de dev (Electron + Vite HMR)
-npm start
+## 💻 Documentação e desenvolvimento
-# Executar linting
-npm run lint
+- [`docs/cloud_features.md`](docs/cloud_features.md): design do pool de contas, do monitoramento de cota e da troca automática.
+- [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): configuração da inspeção TLS (Windows).
+- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): integração com endpoint customizado do OpenCode (em português).
+- [`cli/README.md`](cli/README.md): a ferramenta de linha de comando em Python.
+- [`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).
+- Traduções: [English](README.md), [中文](README.zh-CN.md), [Español](README.es.md).
-# Verificar tipos
-npm run type-check
+### Estrutura
-# Formatar código
-npm run format:write
-
-# Rodar testes
-npm test
-```
-
-### Estrutura do Projeto
-
-```plaintext
+```text
src/
-├── actions/ # Ações do app e orquestração de fluxos
-├── components/ # Componentes React
-│ ├── proxy/ # Componentes da página Proxy (abas avançadas)
-│ ├── usage/ # Componentes de analytics de uso (StatCard, ChartCard)
-│ └── ui/ # Primitivos base de UI (baseados no Radix)
-├── hooks/ # Custom React hooks
-├── ipc/ # Electron IPC + handlers de banco de dados
-├── layouts/ # Componentes de layout (MainLayout + sidebar)
-├── localization/ # Recursos de tradução i18n
-├── routes/ # Páginas TanStack Router (index, usage, proxy, settings)
-├── server/ # Backend NestJS (serviço de gateway proxy)
-├── services/ # Camada de serviços
-├── types/ # Definições de tipos TypeScript + schemas Zod
-└── utils/ # Funções utilitárias
+├── components/ # UI (proxy/, usage/, primitivos ui/)
+├── ipc/ # routers oRPC (account, cloud, config, gateway, usage...)
+├── server/ # gateway proxy NestJS (módulos: proxy, usage)
+├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
+├── routes/ # index, usage, proxy, settings
+├── utils/ # paths, logger, sensitiveDataMasking
+└── tests/ # testes unitários (Vitest) e E2E (Playwright)
+cli/ # CLI Python separada para trocar de conta e consultar cota
+docs/ # notas de design e guias do Proxyman
+scripts/ # setup-dev, build-windows, generate-assets
```
----
+### Scripts
+
+| Comando | O que faz |
+|---|---|
+| `pnpm start` | Roda o app em modo dev (`electron-forge start`, com `DEBUG=electron-forge:*`). |
+| `pnpm run dev` | O mesmo que `start`. |
+| `pnpm run package` | Empacota o app com o Electron Forge, sem gerar instaladores. |
+| `pnpm run make` | Gera instaladores/pacotes para a plataforma atual. |
+| `pnpm run make:win` | Helper de build no Windows: extrai o WiX de `wix314-binaries.zip`, coloca no `PATH` e roda `electron-forge make`. |
+| `pnpm run publish` | Publica pelo Electron Forge. |
+| `pnpm run setup` | Roda `scripts/setup-dev.js`: detecta a toolchain nativa e instala ou orienta a configuração. |
+| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; roda sozinho depois do `pnpm install`. |
+| `pnpm run lint` | ESLint no repositório. |
+| `pnpm run format` | Checagem do Prettier. |
+| `pnpm run format:write` | Prettier com escrita. |
+| `pnpm test` | Testes unitários Vitest (`vitest run`). |
+| `pnpm run test:watch` | Vitest em modo watch. |
+| `pnpm run test:unit` | Vitest (modo padrão). |
+| `pnpm run test:e2e` | Testes E2E com Playwright. |
+| `pnpm run test:all` | Testes unitários e depois Playwright. |
+| `pnpm run type-check` | `tsc --noEmit`. |
## ❓ FAQ
-P: Aviso do Windows SmartScreen ("O Windows protegeu o seu computador") durante a instalação?
+O Windows mostra "O Windows protegeu o seu computador". É normal?
+
+Sim. Os builds não são assinados. Clique em **Mais informações → Executar mesmo assim**.
-Sim, este é um aviso comum para novos aplicativos não assinados. Clique em **"Mais informações"** e depois em **"Executar mesmo assim"**. Veja o aviso no topo do README para mais detalhes.
-P: O app não inicia ao compilar pelo código fonte?
+Minha IDE não alcança o proxy.
+
+O proxy vem desligado: ative-o na página Proxy. A porta padrão é `8045` (`8046` em builds de desenvolvimento) e pode ser trocada ali. Copie a API key da mesma página e confira se há pelo menos uma conta no pool.
-1. Certifique-se de que todas as dependências estão instaladas: `npm install`.
-2. Verifique se a versão do Node.js é >= 20.
-3. Tente deletar `node_modules` e reinstalar.
-4. No Windows, certifique-se de que o WiX Toolset está disponível para o comando `npm run make`.
-P: O login da conta falhou?
+Preciso de uma API key?
+
+Com `api_key` vazia o proxy roda em modo aberto. Quando ativado ele escuta em `0.0.0.0`, então defina uma chave e mantenha-a privada.
-1. Verifique se a conexão com a internet está funcionando.
-2. Tente limpar os dados do app e fazer login novamente.
-3. Verifique se a conta está restrita pelo Google/Claude.
-P: A IDE não consegue conectar ao proxy?
+Dá para usar modelos Claude?
+
+Sim, por mapeamento de modelos nas contas Google do pool, não por contas Claude separadas.
-1. Certifique-se de que o proxy está rodando (indicador verde na barra de status).
-2. Verifique se a porta corresponde à configuração da sua IDE (padrão: `10100`).
-3. Copie a API key da página Proxy e cole nas configurações da sua IDE.
-4. Verifique se pelo menos uma conta está ativa na página de Contas.
-P: A contagem de tokens mostra zero?
+Onde ficam meus tokens?
+
+Num `cloud_accounts.db` separado, com `token_json` e `quota_json` criptografados em AES-256-GCM. A chave mestra fica no cofre de credenciais do sistema via `keytar`. Detalhes em [Modelo de segurança](#modelo-de-segurança).
-1. Este era um bug conhecido em versões anteriores — por favor, atualize para a versão mais recente.
-2. O rastreamento de tokens agora lida corretamente com metadados de streaming e contagens estimadas.
-3. Os dados de uso são atualizados a cada 15 segundos na página de Analytics de Uso.
----
+
+Posso usar comercialmente?
+
+Veja a [Licença](#-licença) antes: o código herdado do AntigravityManager é CC BY-NC-SA 4.0 (não comercial) e o código novo é MIT.
+
+
+
+## Limitações e próximos passos
+
+- O acesso upstream passa pelos endpoints `v1internal` do Cloud Code do Google e por escopos OAuth ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). São APIs internas, sem documentação, que podem mudar sem aviso. O projeto é não oficial e não tem vínculo com o Google nem com a Anthropic.
+- As contas entram via Google OAuth; os modelos Claude são acessados por mapeamento de modelos, não por contas Claude separadas.
+- Os testes end-to-end não rodam no CI (o Electron precisa de ambiente gráfico); rode `pnpm run test:e2e` localmente.
+- O MSI do Windows só é gerado quando o WiX Toolset está disponível na máquina de build; caso contrário o artefato do Windows é o ZIP.
+- Os workflows em `.github/workflows/` foram escritos para o GitHub (chamam o CLI `gh` e o publisher de releases do GitHub), por isso este README não mostra badge de CI.
+- Próximo passo declarado pelo projeto: migrar o código original restante para MIT (veja a [Licença](#-licença)).
## 🤝 Contribuindo
-Contribuições são bem-vindas! Leia o `CONTRIBUTING.md` para mais detalhes.
+Leia o [`CONTRIBUTING.md`](CONTRIBUTING.md) e o [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). As versões são geradas pelo semantic-release a partir de Conventional Commits. Antes de abrir um PR, isto precisa passar:
----
+```bash
+pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
+```
## 📄 Licença
-Este projeto utiliza uma estrutura de licença dual:
-
-- **Código original** do [AntigravityManager](https://github.com/Draculabo/AntigravityManager) por [Draculabo](https://github.com/Draculabo): Licenciado sob [CC BY-NC-SA 4.0](LICENSE).
-- **Todo o código novo, funcionalidades e arquitetura** por [evandrodevbr](https://github.com/evandrodevbr): Licenciado sob a [Licença MIT](LICENSE-MIT).
-
-> 🔄 **Aviso de Migração:** Este projeto está sendo ativamente migrado para uma licença totalmente open-source (MIT). À medida que o código original restante é progressivamente reescrito, todo o projeto será transicionado para MIT. Estamos comprometidos em tornar o Gemini Nexus 100% open-source.
+Licença mista: o código herdado do [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (de Draculabo) é [CC BY-NC-SA 4.0](LICENSE) (não comercial, compartilhamento pela mesma licença); todo o código novo é [MIT](LICENSE-MIT). O projeto está migrando para MIT à medida que o código original restante é reescrito, então confira os dois arquivos antes de qualquer uso comercial.
---
-## 🙏 Créditos
+
-Este projeto foi originalmente um fork de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) criado por [Draculabo](https://github.com/Draculabo). O conceito inicial de proxy e a estrutura base do Electron foram baseados em seu trabalho.
+
-Desde o fork, **a grande maioria do código base foi reescrita, redesenhada e expandida** por [evandrodevbr](https://github.com/evandrodevbr), incluindo mas não se limitando a:
+
-- Redesign completo de UI/UX (navegação, contas, analytics de uso, gerenciamento de proxy)
-- Dashboard de Analytics de Uso com rastreamento de custos, médias de tokens e integração com OpenRouter
-- Monitor de tráfego com inspeção de tokens/custos por requisição
-- Isolamento de ambiente (dev/prod), pipeline CI/CD e infraestrutura de testes
-- Configuração Rápida para IDEs (OpenCode, Cursor, VS Code, Claude Code)
-- Configuração personalizada de preços de modelos
-- Toda a documentação e internacionalização (EN, PT-BR, ES, ZH-CN)
+
diff --git a/assets/readme/hero-prompt.txt b/assets/readme/hero-prompt.txt
new file mode 100644
index 0000000..7c2a848
--- /dev/null
+++ b/assets/readme/hero-prompt.txt
@@ -0,0 +1,11 @@
+Hero raster layer (hero-subject.png), generated with generate_image (openai-codex/gpt-image-2), docs/assets/logo.png as shape reference.
+Background removed with a magenta (#ff00ff) chroma key, then cropped and resized to 760 px.
+Composition: hero.svg places the layer at x=700 y=40 (340x340); node centres 741,86 / 1000,86 / 870,334.
+Final PNGs: rsvg-convert -w 2400 hero[.lang].svg -o hero[.lang].png
+
+Subject: A single isolated 3D hardware object: a machined matte-black metal hub ring, seen slightly from above at a three-quarter angle. Three straight thin metal arms extend outward from the ring (upper-left, upper-right, and straight down), each ending in a small hollow ring node, like a network junction. Inside the main ring sits a softly glowing emerald-green (#10b981) core disc made of frosted glass. Thin emerald light lines run along each arm into the end nodes. Precise industrial product design, clean bevels, subtle brushed-metal texture, no text, no letters, no logo, no watermark.
+Scene: Perfectly flat solid magenta #ff00ff background with no gradient, no texture, no floor, no reflection and no shadow. One isolated subject with generous padding on all sides.
+Composition: Centered, the whole object fully inside the frame with at least 12% empty margin on every side, square framing.
+Lighting: Cool studio key light from the upper left, dark low-key product lighting, emerald glow confined to the core and arm light lines; no magenta tones anywhere on the object.
+Style: Photorealistic product render, dark minimal tech hardware, sharp edges suitable for chroma-key cutout.
+Change: Use the logo only as the shape reference for the ring-with-three-node-arms silhouette; do not reproduce the G/N letters inside the ring, replace them with the glowing emerald core disc.
diff --git a/assets/readme/hero-subject.png b/assets/readme/hero-subject.png
new file mode 100644
index 0000000..6cbc265
Binary files /dev/null and b/assets/readme/hero-subject.png differ
diff --git a/assets/readme/hero.es.png b/assets/readme/hero.es.png
new file mode 100644
index 0000000..23cf72b
Binary files /dev/null and b/assets/readme/hero.es.png differ
diff --git a/assets/readme/hero.es.svg b/assets/readme/hero.es.svg
new file mode 100644
index 0000000..42dd92d
--- /dev/null
+++ b/assets/readme/hero.es.svg
@@ -0,0 +1,66 @@
+
diff --git a/assets/readme/hero.png b/assets/readme/hero.png
new file mode 100644
index 0000000..213ef76
Binary files /dev/null and b/assets/readme/hero.png differ
diff --git a/assets/readme/hero.pt-BR.png b/assets/readme/hero.pt-BR.png
new file mode 100644
index 0000000..08ad2c6
Binary files /dev/null and b/assets/readme/hero.pt-BR.png differ
diff --git a/assets/readme/hero.pt-BR.svg b/assets/readme/hero.pt-BR.svg
new file mode 100644
index 0000000..c35fd1a
--- /dev/null
+++ b/assets/readme/hero.pt-BR.svg
@@ -0,0 +1,66 @@
+
diff --git a/assets/readme/hero.svg b/assets/readme/hero.svg
new file mode 100644
index 0000000..fe8d083
--- /dev/null
+++ b/assets/readme/hero.svg
@@ -0,0 +1,66 @@
+
diff --git a/assets/readme/hero.zh-CN.png b/assets/readme/hero.zh-CN.png
new file mode 100644
index 0000000..2fd910d
Binary files /dev/null and b/assets/readme/hero.zh-CN.png differ
diff --git a/assets/readme/hero.zh-CN.svg b/assets/readme/hero.zh-CN.svg
new file mode 100644
index 0000000..7b9c0a8
--- /dev/null
+++ b/assets/readme/hero.zh-CN.svg
@@ -0,0 +1,66 @@
+