AI Overlay Agent User Guide
Configure and use AI Overlay Agent on Windows. This guide helps you set up API keys via environment variables, customize global hotkeys, use screenshot features, and optimize the overlay app.
What the App Does
AI Overlay Agent is a lightweight, floating Windows assistant. It overlays on top of your work, allowing you to ask questions, grab screenshots for instant visual context, switch models on the fly, and operate completely via global hotkeys.
No license registration, trial period limits, device restrictions, or activation gates are present. Connect your API keys to begin.
First-Time Setup
1. Install and Launch
- Run the provided setup installer for AI Overlay Agent.
- Open the application from your Start Menu or Desktop shortcut.
- If you see an error indicating that an API key is missing, configure your desired AI provider's API key following the instructions below.
API Keys Setup
You must configure at least one API key to query models. Add these variables to your Windows system or user settings.
| Provider | Environment Variable Name |
|---|---|
| OpenRouter | OPENROUTER_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Anthropic | ANTHROPIC_API_KEY |
| Google Gemini | GEMINI_API_KEY |
Basic Use
- Summon the App: Press Ctrl+Shift+Space. The overlay slides in.
- Select a Model: Click the dropdown in the top header to select your configured model.
- Ask a Question: Type into the input box and press Enter to chat.
- Hide the App: Press Esc or Ctrl+Shift+Space again to dismiss it.
Default Shortcuts
| Action | Shortcut |
|---|---|
| Toggle Overlay visibility | Ctrl + Shift + Space |
| Take full-screen screenshot | Ctrl + Shift + S |
| Instantly send prompt | Ctrl + Shift + Enter |
| Export chat to Markdown | Ctrl + Shift + E |
| Toggle HUD (Click-Through) mode | Ctrl + Shift + Alt + T |
HUD (Click-Through) Mode
Pressing Ctrl+Shift+Alt+T activates HUD mode. In this mode:
- The overlay becomes completely transparent to mouse clicks.
- You can click, drag, and interact with the windows underneath the overlay.
- The overlay remains visible on screen so you can read AI responses while working.
- To exit HUD mode and interact with the app again, press Ctrl+Shift+Alt+T again.
Screenshots
The app can take a screenshot of your primary display to provide visual context to the AI.
- Press Ctrl+Shift+S to capture your screen.
- The screen will briefly flash.
- Type your question and press Enter. The screenshot will be sent alongside your text prompt.
- A thumbnail of the captured screenshot will appear in the UI above your input box.
Supported AI Models
Switch models instantly using the dropdown select menu in the app header, or via the model-cycling hotkeys.
| Provider | Required Key Configured |
|---|---|
| OpenRouter models | OPENROUTER_API_KEY |
| OpenAI GPT models | OPENAI_API_KEY |
| Anthropic Claude models | ANTHROPIC_API_KEY |
| Google Gemini models | GEMINI_API_KEY |
UI Configuration
The interface is highly responsive. The easiest way to adjust overlay coordinates or placement is to use the movement shortcuts. Press Ctrl+Shift+0 if you ever need to reset the layout position.
Exporting Chats
Keep records of your chat history. Press Ctrl+Shift+E to export the conversation as an easily readable Markdown file.
Export files are automatically saved to:
User Data Locations
AI Overlay Agent works entirely locally. All configurations, queues, logs, and preferences are saved within your Windows user profile:
| Filename | Stored Information |
|---|---|
| chat_history.json | Local copy of chat logs |
| screenshot_queue.json | Pending image captures |
| preferences.json | Custom UI, theme, and window state preferences |
| config.ini | Saved shortcut configurations |
Privacy & Security
AI Overlay Agent does not send your data to any centralized third-party server besides your chosen AI model provider.
Avoid capturing sensitive documents, financial accounts, or passwords since screenshots and text inputs are forwarded directly to the provider keys you supply.
Troubleshooting
| Reported Problem | How to Resolve |
|---|---|
| App indicates missing API keys | Confirm variables are defined correctly under User or System environment variables, and restart the app. |
| Global shortcuts fail to trigger | Another open application might have captured the shortcut combination. Close competing apps or bind a different combination. |
| Screenshot capture fails | Ensure the app has display-capture permission in Windows settings. |
| Overlay continues showing in screenshots | Exclusion features rely on Windows 10 (2004+) or Windows 11. Check that your Windows version meets these requirements. |
| Model fails to respond | Ensure your selected model matches the API provider key and your account balance or key tier is active. |
Customizing Key Shortcuts
You can override default keybind configurations by directly modifying the local config file.
- Press Win + R, type
%APPDATA%\AIOverlayAgent, and hit Enter. - Find
config.iniand open it in a standard text editor. Run the app at least once to create the file if it's missing. - Locate the
[HOTKEYS]section. - Update individual keys to your liking (e.g., change
ctrl+shift+spacetoctrl+shift+a). Use lowercase letter names joined with plus signs. - Save the configuration file and restart AI Overlay Agent to load your custom shortcuts.