Skip to content
BranchesTags

Repository files navigation

CorvusX Logo

CorvusX: Intelligence in the Shadows

A premium, invisible, always-on-top desktop intelligence overlay that runs silently in the background
Hold a global hotkey to capture the screen, stream system audio, speak to the AI assistant, or simulate human-like typing directly into active editors — all in complete stealth.

Platform Support Electron React & Tailwind LLM Engine Multimodal Input License

Table of Contents

Overview

CorvusX is a high-performance, translucent, click-through desktop overlay designed to serve as a stealth copilot during interviews, debugging sessions, meetings, and presentations. Operating persistently on top of all active application windows, it runs silently in the background, listening to global shortcuts.

Users can capture screen regions (routed directly to Gemini/OmniKey multimodal vision models), capture voice inputs mixed with desktop audio loopback streams, and receive context-aware solutions. CorvusX features a Ghost Keyboard Mode that listens to global keyboard events and a Ghost Writer typing simulator that types answers back into active code editors with human-like tempo, simulated typos, and automatic indentation alignment.

The backend connects directly to Google Gemini APIs or routing-optimized reverse proxies using the OmniKey API key manager, enabling high-performance multimodal reasoning without local hardware strain.

Why CorvusX

Standard AI assistants force you to switch windows, copy-paste errors, or disrupt the natural workflow. CorvusX sits invisibly directly on top of your workspace.

Capability Traditional AI Assistants CorvusX
Form Factor Web browser tab or heavy sidebar panel Stealth HUD overlay, transparent and click-through
Context Capture Manual copy-pasting or file uploading Instant regional screenshots and text extraction via hotkey
Audio Processing Simple microphone transcription Mixed Microphone & System Audio capture for full meeting context
Code Injection Copy button, manually pasting into IDE Ghost Writer simulator typing directly into active cursor position
Response Stealth Bright white screens, clear indicators Glassmorphic overlay with opacity tuning and pulse toggles
Sharing Security Browser window displays prompts to screenshare Content Protection hiding overlay from Discord/Zoom/Teams
Input Capture Requires clicking text boxes to type Ghost Keyboard Mode mirroring keystrokes from other apps

Key Features

🕵️ Stealth HUD Overlay

  • Always-On-Top Glassmorphic UI: Translucent styling with HSL tailored dark backdrops, smooth gradient borders, and customizable opacity.
  • Skip Taskbar & Dock: Operates without taskbar entries or system dock visibility to minimize exposure.
  • Dynamic Window Resizing: Renderer-driven height matching using ResizeObserver and MutationObserver to automatically resize the Electron container to fit content.

⌨️ Ghost Input & Simulation

  • Ghost Keyboard Mode: Uses global key hooks (uiohook-napi) to passively capture keystrokes from active editors or browsers and pipe them directly into the overlay's chat field.
  • Ghost Writer typing simulation: Types responses character-by-character back into the active editor.
  • Mistyping & Error Simulation: Features a realistic 7% typo rate with backspace corrections.
  • Auto-Indentation Alignment: Automatically strips leading indentation spaces of generated code to avoid formatting conflicts with IDE auto-formatters.
  • Adaptive Typing Speed: Models human keystroke intervals (100ms - 250ms delay).

🎙️ Audio Capture & Desktop Loopback

  • Microphone & System Audio Mixing: Combines microphone input with desktop loopback audio dynamically to transcribe both sides of a meeting or interview.
  • Echo Loop Prevention: Restricts delayed microphone audio routing to prevent feedback loops.
  • Diagnostic Audio Loopback: Toggleable live 1.0-second delayed loopback player to diagnose audio streams.

🧠 Multimodal AI Pipeline

  • Google Gemini & OmniKey API: Supports standard cloud connections to Gemini models alongside OmniKey unified key manager endpoints.
  • Multimodal Screen Vision: Performs text and layout analysis from screenshot queues directly via native LLM vision capabilities.
  • Alternate Mode Engine: Switch between Code Mode (delivering direct, comment-free code blocks) and General Mode (delivering conversational, single-paragraph responses).

Architecture

CorvusX divides operations between an Electron Main process managing OS-level window wrappers, global input listeners, and API gateways, and a React renderer process driving the glassmorphic user interface.

graph TD
    subgraph Host OS
        GK[uIOhook Global Input Listener]
        SC[Screen Capture Engine]
        AC[Microphone & Desktop Loopback Audio]
        KB[Keyboard Event Simulation]
    end

    subgraph Electron Main Process
        Main[main.ts - AppState Manager]
        WinH[WindowHelper.ts - Geometry & Protection]
        IPCH[ipcHandlers.ts - Event Channel Router]
        LLMH[LLMHelper.ts - Gemini/OmniKey Client]
        ProcH[ProcessingHelper.ts - Pipeline Orchestration]
        ScrH[ScreenshotHelper.ts - File Cache Manager]
        GhostH[GhostKeyboardHelper.ts - Key Mirroring]
        TypeS[TypingSimulator.ts - Human Keystroke Engine]
        ShH[shortcuts.ts - Global Hotkey Registry]
        ConfH[ConfigHelper.ts - config.json Persistence]
    end

    subgraph React Renderer Process
        App[App.tsx - Layout & Theme Sync]
        QueuePage[Queue.tsx - Command Bar & Queue View]
        SolPage[Solutions.tsx - Solutions Renderer]
        DebPage[Debug.tsx - Diff Code Viewer]
        Onb[OnboardingWizard.tsx - Setup Wizard]
        ModSel[ModelSelector.tsx - Settings Accordion]
        Utils[utils.ts - Custom Markdown Parser]
    end

    GK -->|Pass Keyboard Hooks| GhostH
    SC -->|Capture PNG File| ScrH
    AC -->|Encode Base64 Buffer| App
    TypeS -->|Simulate KeyTap| KB
    
    Main --> WinH & ScrH & LLMH & ProcH & GhostH & TypeS & ShH & ConfH
    IPCH <-->|Preload ContextBridge| App
Loading
ASCII fallback (click to expand) 
┌────────────────────────────────────────────────────────────────────────┐
│                              CorvusX Client                            │
│                                                                        │
│   ┌──────────────────┐    ┌────────────────────────────────────────┐   │
│   │    Host OS       │    │         React Renderer (UI)            │   │
│   │                  │    │                                        │   │
│   │ ┌──────────────┐ │    │  ┌────────────┐  ┌──────────┐ ┌──────┐ │   │
│   │ │ uIOhook      ├─┼───►│  │Onboarding  │  │ Queue    │ │ Debug│ │   │
│   │ │ Key Hook     │ │    │  │Wizard      │  │ (HUD)    │ │ View │ │   │
│   │ └──────────────┘ │    │  └────────────┘  └──────────┘ └──────┘ │   │
│   │ ┌──────────────┐ │    │  ┌────────────┐  ┌──────────┐          │   │
│   │ │ Screen/Audio │ │    │  │Model       │  │ Solutions│          │   │
│   │ │ Capture      ├─┼───►│  │Selector    │  │ Renderer │          │   │
│   │ └──────────────┘ │    │  └────────────┘  └──────────┘          │   │
│   └────────┬─────────┘    └───────────────────▲────────────────────┘   │
│            │                                  │                        │
│   ┌────────▼──────────────────────────────────┴────────────────────┐   │
│   │                     Electron Main Process                      │   │
│   │                                                                │   │
│   │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐      │   │
│   │  │ WindowHelper │  │ IPCHandlers  │  │ ProcessingHelper │      │   │
│   │  │ Protection   │  │ IPC Channels │  │ Flow Control     │      │   │
│   │  └──────────────┘  └──────────────┘  └──────────────────┘      │   │
│   │                                                                │   │
│   │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐      │   │
│   │  │ LLMHelper    │  │ GhostKeyboard│  │ TypingSimulator  │      │   │
│   │  │ Gemini/Proxy │  │ Key Listener │  │ Typo Engine      │      │   │
│   │  └──────────────┘  └──────────────┘  └──────────────────┘      │   │
│   │                                                                │   │
│   │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐      │   │
│   │  │ ConfigHelper │  │ Shortcuts    │  │ ScreenshotHelper │      │   │
│   │  │ Settings file│  │ Hotkey Bind  │  │ File Manager     │      │   │
│   │  └──────────────┘  └──────────────┘  └──────────────────┘      │   │
│   └────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘

Pipeline Flow and How It Works

flowchart TD
    A["Trigger Hotkey\nCmd/Ctrl+H or Shift+V"] --> B{Input Modality}
    
    B -->|"Visual Screenshot"| C["Hide overlay window\nCapture desktop screenshot\nRestore overlay window"]
    C --> D["Multimodal Vision Pipeline Processing"]
    D --> E["Push image paths to Screenshot Queue"]
    
    B -->|"Audio Stream"| F["Record microphone audio\nMix with system loopback (if active)"]
    F --> G["Encode audio to Base64 buffer"]
    
    E --> H{Run Intent Engine}
    G --> H
    
    H --> I["Evaluate LLM Prompt (Gemini / OmniKey)\nrespecting Mode (Code / General)"]
    I --> J["Render response & thoughts in Solutions View\n(Show side-by-side Diff comparison if debugging)"]
    
    J --> K["Optionally copy result (Cmd/Ctrl+Alt+C)\nor simulate human-like typing (Cmd/Ctrl+Alt+K)"]
Loading
ASCII fallback (click to expand) 
Trigger Hotkey (e.g. Cmd+H for screenshot, Cmd+Shift+V for voice)
      │
      ├──► Visual Mode:
      │    1. Hide overlay window instantly.
      │    2. Capture desktop screen screenshot.
      │    3. Restore overlay window.
      │    4. Route captured images to Gemini/OmniKey vision models.
      │    5. Add image files to the cache queue (max 5 files).
      │
      └──► Audio Mode:
           1. Capture microphone stream.
           2. Combine with system desktop output buffer.
           3. Stop recording and encode to Base64 string.
      │
      ▼
Execute Processing (Gemini / OmniKey API Proxy)
      │
      ├──► Code Mode: Extracts direct, clean, formatted code blocks.
      └──► General Mode: Extracts direct, conversational text sentences.
      │
      ▼
Render Output in solutions panel
      │
      ├──► Initial Answer: Displays thoughts, analysis, and code.
      └──► Debug Cycle: Renders side-by-side comparative diffs (added/removed highlights).
      │
      ▼
Action Triggers
      │
      ├──► Copy: Save clean solution to system clipboard.
      └──► Ghost Writer: Type character-by-character into editor cursor.

Visual UI Guide

The CorvusX user interface is a compact, dark-themed control hub that dynamically resizes to remain unobtrusive:

UI Panel Description Interaction Controls
Stealth Command Bar Floating, horizontal bar providing main utility states and status LED indicators. Draggable via top area. Buttons for Microphone Record, Chat Toggle, Mode Switch, Settings Panel, and hotkey listings.
Onboarding Wizard A 6-step initialization setup wizard appearing on first boot to customize user styling and connection setups. Includes Background opacity sliders, Theme choices, Provider selects, API Key entries, Connection latency testers, and Shortcut maps.
Settings & Models Panel A collapsible accordion panel divided into configuration segments (AI, Audio, and UI preferences). Limit height to 50% of the screen height. Toggles for system audio mixing, mic device selection, and live 1.0s delayed loopback test.
Keyboard Shortcuts Modal Hotkey binding overlay designed to record new keypress combinations for active shortcuts. Displays active key maps. Select "Record Key", type a 2-3 key combo, and select "Apply Changes" to save to configuration.
Chat & Audio Panel Standard messaging overlay allowing textual inputs alongside attached screenshot files. Prompt input box that supports Ghost Keyboard Mirroring, attachment lists, and a "Regenerate Last Response" control.
Solutions & Diff Panel Full screen code displaying area. If a debugging screenshot is taken, it splits to compare code versions. Side-by-side syntax-highlighted editor boxes. Highlights lines in red (removed) or green (added).

Access and Launch Instructions

Open Source Source Run

To clone, install dependencies, and run the development server locally:

# 1. Clone the project repository
git clone https://github.com/Felix-au/CorvusX-Intelligence-in-the-Shadows.git
cd CorvusX-Intelligence-in-the-Shadows

# 2. Install dependencies (using Sharp workaround if build errors occur)
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --ignore-scripts
npm rebuild sharp

# 3. Start the application
npm start

(Starts the Vite dev server on port 5180 and launches the Electron application client).

Release Binaries

v1.0.0 is officially released! Standalone portable executables, installers, and ZIP archives can be accessed directly in the Releases section of this repository.

To compile and package your own native binaries from source:

  • Package Production Installer (NSIS): 
    npm run dist
  • Package Portable Windows Executable: 
    npm run build:win:portable
    (Binary packages are saved in the release/ directory).

Web Access

CorvusX is designed exclusively as a native desktop application to support global OS keyboard listeners and screen capture APIs. A standard web version is not available; however, the client queries cloud endpoints (Google AI Studio and the OmniKey reverse proxy hosted on Render) to process prompt inputs.

Troubleshooting and Failsafes

Troubleshooting Guide

Issue Root Cause Resolution
Sharp Build Failures Node-gyp compiling binary incompatibilities with standard installer scripts. Run SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --ignore-scripts, followed by npm rebuild sharp to force compile.
Application Launch Blockers Local port 5180 is occupied by another process. Kill the process occupying port 5180 or update the dev server port mapping inside vite.config.ts.
Ghost Keyboard Duplicating Keys Keyboard hooks triggered while the CorvusX window is focused. The main process automatically ignores key mirroring when the overlay window is active. Simply click away to resolve.
Slow Audio Processing Large audio files or slow networks. Limit voice recording length. Verify connection latency in Settings using the Test Connection button.

Core Failsafes

  • Screen Share Shielding: The application applies window content protection (setContentProtection(true)) and sets the opacity of the always-on-top window to 0.99. This ensures that screen capture or streaming platforms (Zoom, Discord, MS Teams, etc.) render the CorvusX window as completely black or invisible, preserving your privacy.
  • Echo Loop Prevention: When delayed microphone loopback diagnostics are active, the system isolates delayed microphone audio to physical speakers while keeping system capture silent. If active system desktop audio is detected, the HUD displays "Live loopback active (System audio detected! 🔊)" and limits gains to prevent screeching feedback loops.

Author

Felix-au (Harshit Soni)

Built for professionals who need elite cognitive intelligence operating in the shadows.

About

A premium, translucent, always-on-top Electron HUD overlay that acts as a stealth desktop copilot. Integrates real-time multimodal screen vision, mixed microphone and system audio loopback capture, global key mirroring, and human-like typing simulation.

Topics

always-on-topaudio-loopingautomationcopilotdesktop-assistantdeveloper-toolselectrongemini-apiglobal-hotkeyskeyboard-emulationmultimodal-ainodejsoverlayproductivity-toolsreactstealth-aitailwindcsstypescriptwindows-desktop

Resources

Readme
License
Activity

Stars

60 stars

Watchers

21 watching

Forks

33 forks
Report repository

Releases

Contributors

Languages