gemini-nexus/README.pt-BR.md

Gemini Nexus

🚀 Gateway de IA multi-contas profissional para Google Gemini & Claude

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?
• 🎯 Funcionalidades
• 📸 Screenshots
• ⚡ Instalação e Início Rápido
• 🛠️ Stack Tecnológica
• 💻 Desenvolvimento
• ❓ FAQ
• 🤝 Contribuindo
• 📄 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

---

⚡ 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.

(Consulte o aviso no topo desta página se você estiver usando o Windows e encontrar o prompt do SmartScreen).

🔌 Usando com IDEs de IA

Com o aplicativo rodando e pelo menos uma conta adicionada, configure sua IDE preferida (Cursor, Windsurf, OpenCode, etc.):

API Base URL:  http://localhost:10100/v1
API Key:       (copie da página Proxy no app)
Model:         gemini-3-flash  (ou qualquer modelo mapeado)

🛠️ Compilando pelo Código Fonte

Pré-requisitos

• Node.js v20 ou superior
• npm (este projeto usa package-lock.json)

Passos

# Clone o repositório
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus

# Instale as dependências
npm install

# Inicie o modo de desenvolvimento
npm start

# Compile para produção (ex: instalador Windows)
npm run make

---

🛠️ Stack Tecnológica

Categoria	Tecnologias
Core	Electron, React 19, TypeScript
Build	Vite, Electron Forge
Estilização	Tailwind CSS v4, Radix UI, Lucide Icons
Estado	TanStack Query, TanStack Router
Backend	NestJS (gateway interno), ORPC (RPC type-safe)
Banco de Dados	Better-SQLite3, Drizzle ORM
Gráficos	Nivo (Line, Bar, Pie)
i18n	react-i18next
Testes	Vitest, Playwright

---

💻 Desenvolvimento

# Iniciar ambiente de dev (Electron + Vite HMR)
npm start

# Executar linting
npm run lint

# Verificar tipos
npm run type-check

# Formatar código
npm run format:write

# Rodar testes
npm test

Estrutura do Projeto

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

---

❓ FAQ

P: Aviso do Windows SmartScreen ("O Windows protegeu o seu computador") durante a instalação?

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?

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?

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?

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?

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.

---

🤝 Contribuindo

Contribuições são bem-vindas! Leia o CONTRIBUTING.md para mais detalhes.

---

📄 Licença

Este projeto utiliza uma estrutura de licença dual:

• Código original do AntigravityManager por Draculabo: Licenciado sob CC BY-NC-SA 4.0.
• Todo o código novo, funcionalidades e arquitetura por evandrodevbr: Licenciado sob a Licença 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.

---

🙏 Créditos

Este projeto foi originalmente um fork de AntigravityManager criado por 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, 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)