gemini-nexus/README.es.md

Gemini Nexus

🚀 Gateway de IA multi-cuenta profesional para Google Gemini y Claude

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.

---

📖 Tabla de Contenidos

• ✨ ¿Por qué Gemini Nexus?
• 🎯 Características
• 📸 Capturas de Pantalla
• ⚡ Instalación e Inicio Rápido
• 🛠️ Stack Tecnológico
• 💻 Desarrollo
• ❓ Preguntas Frecuentes
• 🤝 Contribuir
• 📄 Licencia

---

✨ ¿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

☁️ 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

---

📸 Capturas de Pantalla

---

⚡ Instalación e Inicio Rápido

📦 Descarga

Puedes descargar los binarios precompilados más recientes para Windows, macOS y Linux desde nuestra página de 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.):

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

# 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

---

🛠️ 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

# 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

---

❓ Preguntas Frecuentes

P: ¿Aviso de Windows SmartScreen ("Windows protegió su PC") durante la instalación?

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?

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ó?

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?

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.

---

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor lee CONTRIBUTING.md para más detalles.

---

📄 Licencia

CC BY-NC-SA 4.0

---

⚠️ Aviso Legal

Warning

Solo con Fines Educativos

Este proyecto está destinado exclusivamente a fines educativos y de investigación. Se proporciona "tal cual" sin ninguna garantía. El uso comercial está estrictamente prohibido.

Al utilizar este software, aceptas que no lo usarás para ningún fin comercial y eres el único responsable de asegurar que tu uso cumpla con todas las leyes y regulaciones aplicables. Los autores y colaboradores no son responsables del mal uso o los daños derivados de la utilización de este software.

---

🙏 Créditos

Gemini Nexus es una versión significativamente mejorada y expandida del proyecto original AntigravityManager creado por Draculabo. Toda la arquitectura fundamental y diseño fueron realizados por el autor original.