[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81365":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":12,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":10,"rankLanguage":10,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":17,"hasPages":17,"topics":19,"createdAt":10,"pushedAt":10,"updatedAt":20,"readmeContent":21,"aiSummary":22,"trendingCount":14,"starSnapshotCount":14,"syncStatus":23,"lastSyncTime":24,"discoverSource":25},81365,"hades-agent","euvictorldev\u002Fhades-agent","euvictorldev","Hades Agent: An invisible, ultra-fast desktop AI companion built with Electron and Gemini Live API. Featuring real-time voice streaming, a native Stealth Mode (invisible to OBS\u002Fscreen-shares), lightning-fast web search, plus background memory dreaming.","",null,"TypeScript",40,9,0,3,"MIT License",false,"master",[],"2026-06-12 02:04:14","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fres.cloudinary.com\u002Fdmii83n8i\u002Fimage\u002Fupload\u002Ffl_preserve_transparency\u002Fv1779237561\u002Fhades-agent_cx7vq7.jpg?_s=public-apps\" alt=\"Hades Banner\" width=\"100%\" style=\"border-radius: 16px; max-width: 800px; box-shadow: 0 10px 30px rgba(0, 0, 0, 0.5);\">\n\u003C\u002Fp>\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd width=\"35%\" align=\"center\" valign=\"top\">\n      \u003Cimg src=\"public\u002Ficon\u002Ficon.png\" width=\"280\" style=\"border-radius: 40px; border: 5px solid #ff2a2a; box-shadow: 0 15px 40px rgba(255, 42, 42, 0.4); display: block; margin-bottom: 15px;\" alt=\"Hades Agent Logo\" \u002F>\n      \u003Cp align=\"center\" style=\"margin-top: 10px; margin-bottom: 0;\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-red?style=flat-square&color=150202\" alt=\"License\" style=\"display: inline-block; vertical-align: middle;\" \u002F>\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FElectron-42.0-red?style=flat-square&logo=electron&logoColor=white&color=150202\" alt=\"Electron\" style=\"display: inline-block; vertical-align: middle;\" \u002F>\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FReact-19.0-red?style=flat-square&logo=react&logoColor=61DAFB&color=150202\" alt=\"React\" style=\"display: inline-block; vertical-align: middle;\" \u002F>\n      \u003C\u002Fp>\n    \u003C\u002Ftd>\n    \u003Ctd width=\"65%\" valign=\"top\" style=\"padding-left: 20px;\">\n      \u003Ch1 style=\"margin-top: 0; margin-bottom: 8px;\">Hades Agent \u003Cimg src=\"https:\u002F\u002Fres.cloudinary.com\u002Fdmii83n8i\u002Fimage\u002Fupload\u002Fv1779302517\u002Fhades-tray-icon-128_dks55n.png\" width=\"36\" height=\"36\" align=\"center\" style=\"display: inline-block; vertical-align: middle; margin-left: 6px;\" alt=\"Hades Icon\" \u002F>\u003C\u002Fh1>\n      \u003Cp>\u003Cstrong>Hades Agent is an intelligent virtual desktop assistant (Windows), built with Electron and React. It functions as a \"floating widget\" that offers advanced text chat and a powerful voice transcription mode with real-time insights via Gemini Live.\u003C\u002Fstrong>\u003C\u002Fp>\n      \u003Cp>\u003Cstrong>Security Boundaries:\u003C\u002Fstrong> Sandboxed with \u003Cstrong>zero write access to the system\u003C\u002Fstrong> (cannot natively create, edit, or delete local files via chat). The intelligence is entirely focused on interface support and productivity.\u003C\u002Fp>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\u003Cp align=\"center\" style=\"margin-top: 20px;\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fvictorl-dev\u002FHades-Agent\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FReleases-Download-FF2A2A?style=for-the-badge&logo=github\" alt=\"Releases\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fvictorl-dev\u002FHades-Agent\u002Fblob\u002Fmaster\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green?style=for-the-badge\" alt=\"License: MIT\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fvictorl-dev\u002FHades-Agent\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuilt%20With-Gemini%20Live%20API-blueviolet?style=for-the-badge\" alt=\"Built with Gemini Live\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fvictorl-dev\u002FHades-Agent\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPlatform-Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white\" alt=\"Platform: Windows\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n## Key Features\n\n- **MiniChat:** A minimalist floating chat, conversing directly with the AI, designed for quick access and global shortcuts.\n- **Susurro Mode (Real-Time Insights):** Much more than a simple voice recorder. By activating the \"Suggestions\u002FInsights\" mode, Hades stops acting just as a transcriber and actively listens to your context. It works as a *brainstorming partner*, identifying questions, problems, or discussion topics in real time and providing ideas, quick answers, and solutions directly on the screen. The model has been strictly instructed (via `insight_rules.md`) to be concise, agile, and to hide internal monologues (CoT), delivering only the final value directly for you to read while speaking.\n- **Persistent History:** The application automatically saves your text and audio sessions in the backend, generating smart titles based on the context of the conversation.\n- **Overlay & Glassmorphism UI:** Premium design with fluid transparency, side menus, and high responsiveness.\n- **Native Resizing:** System-level optimized window resizing loop (`requestAnimationFrame` + IPC fast-fire) for immaculate performance on Windows.\n\n---\n\n## Tech Stack\n\n- **Language:** TypeScript \u002F JavaScript (Node.js + Browser)\n- **Desktop Framework:** Electron (v42+)\n- **Frontend:** React 19 + Vite 8\n- **Styling:** Pure Vanilla CSS with CSS Variables & Backdrop Filters\n- **AI and APIs:** `@google\u002Fgenai`, `@google\u002Fgenerative-ai`, `@google-cloud\u002Fspeech`\n- **Audio:** `recordrtc`\n- **Packager:** `electron-builder`\n\n---\n\n## Prerequisites\n\n- Node.js 20 or higher.\n- NPM or pnpm.\n- A valid **Google Gemini API** key.\n- OS: Windows (packaging is focused on `.exe` and portable apps on Windows).\n\n---\n\n## Getting Started\n\n### 1. Clone the Repository\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fvictorl-dev\u002FHades-Agent.git\ncd hades-agent\n```\n\n### 2. Install Dependencies\n\n```bash\nnpm install\n```\n\n### 3. Configure the API Key\n\nIt is not necessary to create a `.env` file manually. When starting the application for the first time, you can configure your API key directly in the system interface:\n1. Open the **Settings** by clicking the gear icon or pressing the global shortcut `Alt + S`.\n2. Enter your **Google Gemini API** key.\n3. The key will be securely encrypted and saved locally by Electron.\n\n### 4. Run in Development Environment\n\nThe command below will start Vite (to compile React) and Electron (your native window) in parallel.\n\n```bash\nnpm run dev\n```\n\n*Note: In case of residual crashes, the command automatically kills stuck 3000 ports and terminates zombie Electron processes.*\n\n---\n\n## Architecture\n\nHades Agent uses a unified Single Window architecture. The main application state toggles the internal interfaces, keeping the Electron window alive and resizing accordingly.\n\n### Directory Structure\n\n```\n├── electron\u002F                 # Main Process Functionality (Electron)\n│   ├── main.js               # Electron entry point\n│   ├── windowManager.js      # Window creation, bounds, and drag\n│   ├── ipcHandlers.js        # IPC Handlers to manage state, files, and events\n│   └── services\u002F             # Backend Services\n│       ├── aiService.js      # Base Gemini integration\n│       └── geminiLiveService.js # WebSocket for Gemini Live (streaming)\n├── public\u002F                   # Static files and icons\n├── src\u002F                      # Frontend Source Code (React)\n│   ├── App.tsx               # Main controller and router (MiniChat ↔ Susurro)\n│   ├── components\u002F           # UI Components\n│   │   ├── chat\u002F             # MiniChat UI (Header, Body, Input)\n│   │   ├── susurro\u002F          # Recorder and insights UI (SusurroHeader, Overlay)\n│   │   └── common\u002F           # Shared menus, icons, and overlays\n│   ├── hooks\u002F                # Custom React Hooks\n│   ├── styles\u002F               # Global and component-specific CSS\n│   ├── types\u002F                # TypeScript Definitions\n│   └── main.tsx              # React initialization point\n├── prompts\u002F                  # Context instructions for AI agents\n├── package.json              # npm and Electron Builder configurations\n└── vite.config.ts            # Vite build configurations\n```\n\n### Data Flow & IPC\n\nHades communicates its graphical interface (React) with APIs and file manipulation (Node.js) through the `contextBridge` defined in `preload.js`. \n\n```\nUser Action (React) \n  → window.electronAPI (Preload) \n    → ipcMain.on \u002F handle (Node.js \u002F Electron) \n      → aiService.js or sessions.json\n        → window.webContents.send (Response to React)\n```\n\n### Key Components\n\n**Sessions System (`sessions.json`)**\n- Transcriptions and conversations are saved in session format. The application asks the AI to generate a short title and permanently saves it to the HDD.\n\n**Real-Time Resizing (`windowManager.js`)**\n- We use the `resize-window-fast` IPC pattern instead of promise-based IPC channels. The client fires fast mouse events via `requestAnimationFrame`, allowing the Electron window to be dragged and expanded at 60fps without Main-Thread delay.\n\n**Integrated Gemini Live**\n- In Susurro mode, we activate `isSuggestionsMode` in the Gemini WebSocket streaming. This instructs the AI model to return instant insights filtering its own \"Internal Monologues\" to avoid polluting the user's final view.\n\n---\n\n## Available Scripts\n\n| Command | Description |\n|---|---|\n| `npm run dev` | Starts development server (React + Electron) with Auto-Reload. |\n| `npm run build` | Builds production only for the React layer. |\n| `npm run package` | Builds the Electron executable for Windows (`.exe`). |\n| `npm run dist` | Builds React and then packages it into installable (`nsis`) and portable formats. |\n| `npm run test` | Runs tests with Vitest. |\n\n---\n\n## Deployment & Packaging\n\nTo distribute the application, use `electron-builder` which is properly configured in `package.json`.\n\n### Generating Installers (Windows)\n\n```bash\nnpm run dist\n```\n\nThis will create a `release\u002F` folder in the root of your project containing:\n- `Hades-Agent-Setup-2.0.1.exe` (Traditional installer)\n- `Hades-Agent-2.0.1-portable.exe` (Standalone app)\n- `.zip` files and optional unpacked files.\n\n---\n\n## Troubleshooting\n\n### Stuck Port Errors (Port 3000)\n**Problem:** Vite reports that port 3000 is already in use.\n**Solution:** The `npm run dev` script tries to kill the port via `kill-port`. If it persists, run in the Windows terminal: \n`npx kill-port 3000`\n\n### Window Freezes on Resize\n**Solution:** Make sure there is no CSS component doing `transition: all` on `.app-container`. CSS layout transitions tied with Electron's ResizeObserver freeze the OS Main Thread.\n\n### Gemini API Returning Error\n**Solution:** Verify if your `.env` was loaded correctly. Since the file is at the root of Electron, `dotenv` initialized in `main.js` will read it. \n\n---\n\n## Settings and API Keys\n\nThe system manages keys dynamically and securely, without the need for exposed `.env` files in the root.\n\n### How to Configure\n\n| Setting | Description | Where to Find \u002F Insert |\n| --- | --- | --- |\n| `GEMINI_API_KEY` | Google Gemini API Key for AI and chat | Settings Menu (`Alt + S`) |\n\n### Access via Electron\n\nThe key entered in the Settings UI is passed to the backend services (`aiService.js`, `geminiLiveService.js`) using the Electron process (via `ipcRenderer.invoke`). The Backend saves these settings and manages them in isolation, preventing access keys from being insecurely transmitted or leaked when building the web application with Vite.\n\n---\n\n## Testing\n\nThe environment is configured to use **Vitest** due to native integration with Vite.\n\n### Running Tests\n\n```bash\n# Run all tests in watch mode\nnpm run test\n\n# To run once in continuous integration (CI)\nnpx vitest run\n```\n\n*Note: Tests can still be expanded to cover IPC (Inter-Process Communication) integrations using mocks for native Electron modules.*\n\n---\n\n## Contributing\n\nIf you want to contribute to the project:\n1. Fork the repository.\n2. Create a branch for your feature (`git checkout -b feature\u002Fmy-feature`).\n3. Commit your changes (`git commit -m 'feat: add my feature'`).\n4. Push to the branch (`git push origin feature\u002Fmy-feature`).\n5. Open a Pull Request.\n\n---\n\n## License\n\nThis project is licensed under the **MIT License**.\n\nThe MIT License is a short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.\n\nCopyright (c) 2026, Victor L. Oliveira\n","Hades Agent 是一个基于 Electron 和 React 构建的智能桌面助手，专为 Windows 用户设计。它以浮动小部件的形式提供高级文本聊天和强大的语音转录功能，并通过 Gemini Live API 实现实时洞察。核心功能包括实时语音流、隐身模式（在 OBS 或屏幕共享中不可见）、快速网络搜索以及后台记忆处理。该应用采用沙盒技术，确保零写入系统权限，专注于界面支持与提升生产力。Hades Agent 适用于需要高效沟通和信息检索的办公场景，特别适合那些重视隐私和安全性的用户。",2,"2026-06-11 04:04:48","CREATED_QUERY"]