Overlay Browser : Your AI companion's second screen — instant, always-on-top, zero distraction.
Global Shortcuts | Floating UI | Profile Persistence | Cross-Platform | Easy to Extend
English
💬 Community: GitHub Discussions | Report Issues | GitHub Profile
Overview · Features · Installation · Usage · Development · FAQ · Contributing
OverlayBrowser is more than a simple browser. It's a lightweight, proof-of-concept overlay tool designed for seamless LLM integration. Toggle a browser window instantly with global shortcuts, dock it conveniently, and persist profiles for quick access. Built with Electron for cross-platform compatibility.
| Traditional Browsers | OverlayBrowser | |
|---|---|---|
| Overlay Mode | No | Yes — floating overlay with global shortcut |
| Profile Persistence | Limited | Yes — save URL, dock position automatically |
| Global Shortcuts | No | Yes — customizable keyboard shortcuts |
| Lightweight | Varies | Yes — minimal footprint, fast startup |
| Easy to Extend | Varies | Yes — clean Electron codebase |
OverlayBrowser provides essential features for quick browser access alongside your LLM tools.
- 🎯 Global Shortcut Toggle — Press
Super+O(Win+O on Windows) to instantly show/hide the overlay from anywhere - 📌 Floating UI — Dock left/right, always-on-top for distraction-free access while you work
- 💾 Profile Persistence — Automatically save and restore URL, dock position, and window state
- ⚙️ Easy Customization — Modify shortcuts, profiles, and behavior via clean, well-organized code
- 🖥️ Cross-Platform — Native support for Windows, macOS, and Linux
- ⚡ Lightweight — Minimal footprint (~100MB), fast startup, efficient resource usage
Key Files:
main.js— Main Electron process, global shortcut registration, window managementrenderer.js— Primary UI for the overlay browserpreload.js/float-preload.js— Secure IPC bridges between renderer and main processesfloat-button.html/float-renderer.js— Floating overlay UI componentsprofiles.json— Profile storage example and documentation
- Windows: Windows 10 or higher
- macOS: 10.15 (Catalina) or higher
- Linux: Ubuntu 18.04+ / Debian 10+ / Fedora 32+
- Memory: 512MB+ recommended
- Storage: 100MB+ available space for installation
- Node.js: Version 14 LTS or higher
- npm: Comes with Node.js
- Git: Optional, for cloning the repository
# Clone the repository
git clone https://github.com/fajarnadril/OverlayBrowser.git
# Navigate to project directory
cd OverlayBrowser
# Install dependencies
npm install
# Start the app in development mode
npm startThe npm start command launches the Electron app (electron .) with hot-reload capabilities, perfect for development and testing.
# Build the app for your platform
npm run buildThis generates an executable installer using electron-builder, configured in package.json. Artifacts are output to a dist/ directory and are ready for distribution.
Expand to view build and configuration details
Build Configuration:
- The build process uses
electron-builderto create platform-specific installers - On Windows: generates
.exeportable executable - On macOS: generates
.dmgapplication bundle - On Linux: generates
.AppImageor.debpackages - All files configured in
package.jsonunder thebuildsection
Environment Setup Tips:
- Use Node Version Manager (nvm) for easy Node.js version switching
- On Windows, you may need Visual C++ build tools for some native modules
- Run
npm listto verify dependency tree
OverlayBrowser is designed to be intuitive and requires minimal configuration out of the box.
- Toggle Overlay: Press the global shortcut (
Super+O/ Win+O) to open or close the floating browser window - Dock Positioning: Use the Dock button in the overlay to switch between left and right positioning
- Load URL: Type or paste any URL in the address bar to navigate
- Persistent Profile: Your current URL and dock position are automatically saved
Profiles are stored in Electron's userData folder:
- Windows:
%APPDATA%\OverlayBrowser\ - macOS:
~/Library/Application Support/OverlayBrowser/ - Linux:
~/.config/OverlayBrowser/
See profiles.json in the repository for an example profile structure.
Changing the Global Shortcut:
- Open
main.jsand locate the shortcut registration code (typically near the top) - Replace the shortcut string (e.g.,
'Super+O') with your preferred combination - Restart the app (
npm start)
Common shortcut formats: Ctrl+Shift+X, Alt+Z, CmdOrCtrl+U
View shortcut conflict troubleshooting
If your chosen shortcut conflicts with system or application shortcuts:
- Windows: Check Settings → Keyboard Shortcuts for reserved keys
- macOS: System Preferences → Keyboard → Shortcuts
- Linux: Varies by desktop environment; check your WM/DE documentation
OverlayBrowser is designed with clean, extensible architecture. Perfect for learning Electron or building custom overlays.
Main Process (main.js):
- Initializes Electron app
- Registers global shortcuts
- Manages window lifecycle and state persistence
- Handles IPC communication with renderer processes
Renderer Process (renderer.js):
- Primary overlay browser UI
- Handles navigation and URL input
- Manages profile loading/saving via IPC
Preload Bridges (preload.js, float-preload.js):
- Secure context bridges between main and renderer
- Exposes safe API methods to renderer processes
- Implements principle of least privilege
Floating UI (float-button.html, float-renderer.js):
- Separate floating window UI
- Dock positioning controls
- Minimize/close button functionality
# Start development server with auto-reload
npm start
# Open DevTools for debugging (Ctrl+Shift+I on the app window)
# Make changes to source files
# App automatically reloads on save- DevTools: Press
Ctrl+Shift+I(Windows/Linux) orCmd+Shift+I(macOS) to open developer tools - Console Logging: Logs from both main and renderer processes appear in DevTools
- Performance: Use DevTools Performance tab to profile rendering and startup time
- Network: DevTools Network tab shows all network requests made by the overlay
For production deployment, consider:
- ✅ Implementing code signing for macOS and Windows
- ✅ Adding auto-update mechanism using
electron-updater - ✅ Implementing security headers and CSP policies
- ✅ Adding crash reporting with services like Sentry
- ✅ Implementing telemetry opt-in (not opt-out)
- ✅ Hardening IPC communication between processes
Q: Why is this called a "Proof-of-Concept"?
A: OverlayBrowser is a PoC designed to demonstrate the core concept of a floating, persistent overlay browser. It's production-ready for personal use but may need enhancements for enterprise deployment (security hardening, update mechanisms, telemetry, etc.).Q: Can I use OverlayBrowser alongside my LLM tools?
A: Yes! That's the primary use case. The global shortcut allows you to quickly toggle the browser while working with any LLM, IDE, or application. It's designed to be non-intrusive.Q: How do I customize the keyboard shortcut?
A: Edit `main.js` and change the shortcut registration string. Common formats: `'Ctrl+Shift+X'`, `'Alt+Z'`, `'CmdOrCtrl+U'`. See the Development section for details.Q: Is my data secure? Where are profiles stored?
A: Profiles are stored locally in Electron's `userData` folder on your machine. No data is uploaded to any server. All IPC communication between processes is isolated and secure.Q: Can I extend OverlayBrowser with custom features?
A: Absolutely! The codebase is clean and well-structured. You can add features like: - Custom toolbar buttons and integrations - Additional keyboard shortcuts - Profile sync to cloud storage - Plugins or extensions system - Custom CSS themingStart by modifying renderer.js or float-renderer.js to add new features.
Q: Does OverlayBrowser work offline?
A: The overlay browser itself works offline. You can still use it to view local HTML files or previously loaded content. However, navigating to online URLs will fail without internet connectivity.Q: What's the performance impact?
A: OverlayBrowser has minimal resource footprint (~50-100MB RAM depending on loaded content). Global shortcuts are registered at OS level with negligible CPU impact. The overlay window only renders when visible.Thanks for considering contributing to OverlayBrowser! We welcome all kinds of contributions.
- Fork the repository on GitHub
- Create a feature branch:
git checkout -b feature/your-feature-name - Make your changes with clear, descriptive commits
- Test your changes locally with
npm start - Push to your fork:
git push origin feature/your-feature-name - Open a Pull Request with a clear description of your changes
- Include a short description of what you're adding or fixing
- Add reproduction steps if fixing a bug
- Include screenshots for UI changes
- Keep commits focused and atomic
- Follow the existing code style and structure
- Test on at least one platform (Windows/macOS/Linux) if possible
# Clone your fork
git clone https://github.com/YOUR_USERNAME/OverlayBrowser.git
cd OverlayBrowser
# Install dependencies
npm install
# Create a feature branch
git checkout -b feature/my-feature
# Make changes and test
npm start
# When ready, push and create a PR
git push origin feature/my-feature- 🐛 Bug fixes and issue resolution
- 🎨 UI/UX improvements
- 📚 Documentation and guides
- 🌍 Translations and internationalization
- ⚡ Performance optimizations
- 🔒 Security improvements
- ✨ New features and enhancements
This project is licensed under the MIT License — see the LICENSE file for details.
The MIT License allows you to use, modify, and distribute OverlayBrowser freely for personal and commercial purposes.
- GitHub Discussions: Share ideas and ask questions in Discussions
- Issues: Report bugs and request features via Issues
- Releases: Download latest version from Releases
Owner / Maintainer: fajarnadril
OverlayBrowser is an open-source project created to explore Electron capabilities and provide a simple, useful tool for LLM integration workflows.
If you find this project helpful, consider:
- ⭐ Giving it a star on GitHub
- 🔄 Sharing it with others
- 💬 Providing feedback and suggestions
- 🤝 Contributing improvements
Have a question or suggestion? Open an issue or start a discussion