Home

CaerusAI User Guide

CaerusAI is a lightweight Windows desktop chat client for interacting with Google Gemini and OpenAI ChatGPT models, with optional live web search grounding.

Installation

1. Download CaerusAI-Setup.msi from the releases page.
2. Run the installer. CaerusAI installs per-user, so no administrator rights are required.
3. Launch CaerusAI from the Start Menu or Desktop shortcut.

First-Time Setup: Adding API Keys

CaerusAI requires at least one API key (Gemini or ChatGPT) to function.

• On first launch, if no key is configured, a dialog will prompt you to enter your Gemini and/or ChatGPT API key.
• You can also edit your keys at any time via the Config button on the toolbar, which opens appsettings.json in your default text editor.
• Configuration is stored locally at:

%LocalAppData%\CaerusAI\appsettings.json

• No keys, chat data, or logs are ever sent anywhere other than the LLM provider you configure.

The Toolbar

Button	Shortcut	Description
New Chat	Ctrl+N	Starts a new saved chat session.
Scratch Chat	Ctrl+T	Starts a temporary chat that is not saved unless you explicitly save it.
Save Chat	Ctrl+S	Saves the current scratch chat as a permanent session.
Delete Session	Ctrl+D	Deletes the currently selected saved session.
Config	—	Opens appsettings.json in your default editor.
About	—	Shows the application name and current version.

The toolbar also includes:

• Provider dropdown — switch between Gemini and ChatGPT.
• Model dropdown — select the model to use for the selected provider.
• Web grounding checkbox — enables live web search grounding for the current message, when supported by the selected provider.

Sessions

• All saved sessions appear in the Sessions panel on the left, sorted most-recent first.
• Click a session to load its conversation history.
• Sessions are stored locally in an embedded SQLite database, so your chat history persists across restarts.
• Long conversations are automatically summarized in the background to preserve context without exceeding model token limits.

Sending Messages

• Type your message in the input box at the bottom of the window.
• Press Enter (or Ctrl+Enter) to send.
• While the model is generating a response, a "Thinking…" indicator appears in the status bar.
• Responses are rendered with support for Markdown formatting, code blocks, tables, and basic math notation.

Web Grounding

When the Web grounding checkbox is enabled, the assistant can perform live web searches to answer questions requiring up-to-date information (news, prices, current events, etc.).

CaerusAI currently supports two grounding search providers for ChatGPT:

• DuckDuckGo (default)
• Yahoo

To change the search provider, edit the WebSearchAdapter field under the ChatGPT section of appsettings.json:

"ProviderConfig": {
  "ChatGPT": {
    "WebSearchAdapter": "DuckDuckGo"
  }
}

Valid values are DuckDuckGo or Yahoo (case-insensitive). If the field is missing or empty, DuckDuckGo is used by default.

Note: Web search providers occasionally rate-limit or temporarily block automated requests. If this happens, CaerusAI will display a clear error message in the chat rather than allowing the model to guess or fabricate an answer. Simply try again in a moment.

Configuration Reference

Key fields in appsettings.json per provider:

Field	Description
ApiKey	Your API key for the provider.
DefaultModel	The model selected by default when the app starts.
ContextSummaryModel	The (usually cheaper/faster) model used for background conversation summarization.
EnableWebGrounding	Whether web grounding is enabled by default for this provider.
WebSearchAdapter	(ChatGPT only) Which search engine to use for grounding: DuckDuckGo or Yahoo.
Models	The list of models shown in the Model dropdown for this provider.

There is also a top-level LogLevel setting:

• 0 — Logging disabled (default).
• 1 — Logs user actions and request/response sizes.
• 2 — Additionally logs full request/response content and web search results, useful for troubleshooting.

Logs are written to:

%LocalAppData%\CaerusAI\logs\caerusai.log

Troubleshooting

• No models appear in the dropdown: Ensure an ApiKey is set for the selected provider in appsettings.json.
• "No API key is configured" message: Add your key via the Config button, or restart the app to trigger the setup dialog.
• Web search errors: These usually mean the search provider temporarily blocked the request. Try again, or switch WebSearchAdapter to the other supported provider.
• Blinking cursor missing in the input box: Click into the input box, or switch sessions to restore focus.

Uninstalling

Uninstall CaerusAI from Settings → Apps (Windows) like any other application. Your saved sessions and configuration in %LocalAppData%\CaerusAI are preserved unless manually deleted.