# oAI A powerful native macOS AI chat application with support for multiple providers, advanced memory management, and seamless Git synchronization. ![oAI Main Interface](Screenshots/1.png) ## Features ### 🤖 Multi-Provider Support - **OpenAI** - GPT models with native API support - **Anthropic** - All Claude models - **OpenRouter** - Access to 300+ AI models from multiple providers - **Ollama** - Local model inference for privacy ### 💬 Core Chat Capabilities - **Streaming Responses** - Real-time token streaming for faster interactions - **Conversation Management** - Save, load, export, and search conversations - **File Attachments** - Support for text files, images, and PDFs - **Image Generation** - Create images with supported models (DALL-E, Flux, etc.) — renders inline in chat - **Reasoning / Thinking Tokens** - Stream live reasoning from thinking-capable models (DeepSeek R1, Claude 3.7+, o1/o3, Qwen); configurable effort level (High/Medium/Low/Minimal); collapsible block auto-expands while thinking and collapses when the answer arrives - **Online Mode** - DuckDuckGo and Google web search integration - **Session Statistics** - Track token usage, costs, and response times - **Command History** - Navigate previous commands with searchable modal (⌘H) ### 🧠 Enhanced Memory & Context System - **Smart Context Selection** - Automatically select relevant messages to reduce token usage by 50-80% - **Message Starring** - Mark important messages to always include them in context - **Semantic Search** - AI-powered search across conversations using embeddings - **Progressive Summarization** - Automatically summarize old portions of long conversations - **Multi-Provider Embeddings** - Support for OpenAI, OpenRouter, and Google embeddings ![Settings Interface](Screenshots/2.png) ### 🔧 Model Context Protocol (MCP) Advanced filesystem access for AI models with fine-grained permissions: - **Read Access** - Allow AI to read files in specified folders - **Write Access** - Optional write permissions for file modifications - **Gitignore Support** - Respects .gitignore patterns when listing/searching - **Folder Management** - Add/remove allowed folders with visual status - **Search Operations** - Find files by name or content across allowed directories ### 🔄 Git Synchronization Seamless conversation backup and sync across devices: - **Auto-Sync** - Automatic export and push to Git repository - **Smart Triggers** - Sync on app start, idle, goodbye phrases, model switches, or app quit - **Multi-Provider Support** - GitHub, GitLab, Gitea, and custom Git servers - **Conflict Prevention** - Warning system for multi-machine usage - **Manual Sync** - One-click sync with progress indication ![Model Selector](Screenshots/3.png) ### ⚡ Shortcuts & Agent Skills - **Shortcuts** - Personal slash commands that expand to prompt templates; optional `{{input}}` placeholder for inline input - **Agent Skills (SKILL.md)** - Markdown instruction files injected into the system prompt; compatible with skill0.io, skillsmp.com, and other SKILL.md marketplaces; import as `.md` or `.zip` bundle with attached data files ### 🖥️ Power-User Features - **Bash Execution** - AI can run shell commands via `/bin/zsh` (opt-in, with per-command approval prompt) - **iCloud Backup** - One-click settings backup to iCloud Drive; restore on any Mac; API keys excluded for security - **Paperless-NGX Integration** *(Beta)* - Search, read, and interact with documents in a self-hosted Paperless instance - **Tool Call Inspection** - Click any 🔧 tool message to expand input/output JSON for all tool calls ### 📧 Email Handler (AI Email Assistant) Automated email responses powered by AI: - **IMAP Polling** - Monitor inbox for emails with specific subject identifiers - **AI-Powered Responses** - Generate contextual replies using any AI provider - **SMTP Integration** - Send replies via SMTP with TLS support - **Rate Limiting** - Configurable emails per hour limit - **Email Threading** - Proper In-Reply-To headers for email chains - **Secure Storage** - AES-256-GCM encryption for all credentials - **Email Log** - Track all processed emails with success/error status ### 🎨 UI/UX - Native macOS interface with dark/light mode support - Markdown rendering with syntax highlighting - Customizable text sizes (GUI, dialog, input) - Footer stats display (messages, tokens, cost, sync status) - Header status indicators (MCP, Online mode, Git sync) - Responsive message layout with copy buttons - **Model Selector (⌘M)** - Filter by capability (Vision / Tools / Online / Image Gen / Thinking 🧠), sort by price or context window, search by name or description, per-row ⓘ info button - **Localization** - UI fully translated into Norwegian Bokmål, Swedish, Danish, and German; follows macOS language preference automatically ![Advanced Features](Screenshots/4.png) ## Installation ### Download Download the latest release from the [Releases page](https://gitlab.pm/rune/oai-swift/releases). Two builds are available: - **oAI-x.x.x-AppleSilicon.dmg** — for Macs with an Apple Silicon chip (M1 and later) - **oAI-x.x.x-Universal.dmg** — runs natively on both Apple Silicon and Intel Macs ### Installing from DMG 1. Open the downloaded `.dmg` file 2. Drag **oAI.app** into the **Applications** folder 3. Eject the DMG 4. Launch oAI from Applications or Spotlight ### First Launch — Gatekeeper Warning oAI is **signed by the developer** but has **not yet been notarized by Apple**. Notarization is Apple's automated malware scan — the app itself is safe, but macOS Gatekeeper may block it on first launch with a message saying the app "cannot be opened because the developer cannot be verified." To open the app, you have two options: **Option A — Right-click to open (quickest):** 1. Right-click (or Control-click) `oAI.app` in Applications 2. Select **Open** from the context menu 3. Click **Open** in the dialog that appears 4. After doing this once, the app opens normally from then on **Option B — Remove the quarantine flag via Terminal:** ```bash xattr -dr com.apple.quarantine /Applications/oAI.app ``` This command removes the quarantine attribute that macOS attaches to files downloaded from the internet. The `-d` flag deletes the attribute, `-r` applies it recursively to the app bundle. Once removed, macOS no longer blocks the app from launching. ### Requirements - macOS 14.0 (Sonoma) or later - An API key for at least one supported provider (OpenRouter, Anthropic, OpenAI, or Google), or Ollama running locally ## Configuration ### API Keys Add your API keys in Settings (⌘,) → General tab: - **OpenAI** - Get from [OpenAI Platform](https://platform.openai.com/api-keys) - **Anthropic** - Get from [Anthropic Console](https://console.anthropic.com/) or use OAuth - **OpenRouter** - Get from [OpenRouter Keys](https://openrouter.ai/keys) - **Ollama** - Base URL (default: http://localhost:11434) - **Google** - API key used for Google Custom Search (web search) and Google embeddings (semantic search) — not a chat provider ### Essential Settings #### General Tab - **Default Provider** - Select your preferred AI provider - **Streaming** - Enable/disable real-time response streaming - **Memory** - Control conversation context (on/off) - **Online Mode** - Enable web search integration - **Max Tokens** - Set maximum response length - **Temperature** - Control response randomness (0.0 - 2.0) - **Reasoning** - Enable thinking tokens for supported models; set effort level (High/Medium/Low/Minimal); optionally hide reasoning content from chat #### Advanced Tab - **Smart Context Selection** - Reduce token usage automatically - **Semantic Search** - Enable AI-powered conversation search - **Progressive Summarization** - Handle long conversations efficiently #### Sync Tab - **Repository URL** - Git repository for conversation backup - **Authentication** - Username/password or access token - **Auto-Save** - Configure automatic save triggers - **Manual Sync** - One-click synchronization #### Email Tab - **Email Handler** - Configure automated email responses - **IMAP/SMTP Settings** - Email server configuration - **AI Provider** - Select which AI to use for responses - **Rate Limiting** - Control email processing frequency ## Slash Commands ### Model & Chat - `/help` - Show help and available commands - `/model` - Open model selector (⌘M) - `/clear` - Clear current conversation - `/retry` - Regenerate last response - `/info [model]` - Display model information ### Conversation Management - `/save ` - Save current conversation - `/load` or `/list` - List and load saved conversations (⌘L) - `/delete ` - Delete a saved conversation - `/export [filename]` - Export conversation - `/history` - Open command history modal (⌘H) ### Provider & Settings - `/provider [name]` - Switch or display current provider - `/config` or `/settings` - Open settings (⌘,) - `/stats` - View session statistics - `/credits` - Check API credits/balance (OpenRouter) ### Features - `/memory ` - Toggle conversation memory - `/online ` - Toggle online/web search mode - `/mcp ` - Manage MCP filesystem access ### MCP (Model Context Protocol) - `/mcp add ` - Grant AI access to a folder - `/mcp remove ` - Revoke folder access - `/mcp list` - Show allowed folders - `/mcp write ` - Enable/disable file write permissions - `/mcp status` - Display MCP configuration ## File Attachments Attach files to your messages using the syntax: `@/path/to/file` **Example:** ``` Can you review this code? @~/project/main.swift ``` **Supported formats:** - **Text files** - Any UTF-8 text file (.txt, .md, .swift, .py, .json, etc.) - **Images** - PNG, JPG, WebP (for vision-capable models) - **PDFs** - Document analysis with vision models **Limits:** - Maximum file size: 10 MB - Text files truncated after 50 KB (head + tail shown) - Image dimensions automatically scaled for optimal processing ## Keyboard Shortcuts - `⌘M` - Open model selector - `⌘,` - Open settings - `⌘N` - New conversation - `⌘L` - List saved conversations - `⌘H` - Command history - `Esc` - Cancel generation / Close dropdown - `↑/↓` - Navigate command dropdown (when typing `/`) - `Return` - Send message - `Shift+Return` - Insert newline ## Advanced Features ### Smart Context Selection Reduce token usage by 50-80% without losing context quality: - Always includes last 10 messages - Prioritizes user-starred messages - Includes high-importance messages (based on cost and length) - Respects model context limits automatically ### Semantic Search Find conversations by meaning, not just keywords: - AI-powered embeddings using OpenAI, OpenRouter, or Google - Search across all conversations semantically - Cost-effective: ~$0.04 one-time for 10k messages - Toggle semantic search in conversation list ### Progressive Summarization Handle 100+ message conversations gracefully: - Automatically summarizes old portions of conversations - Keeps last 20 messages in full - Summaries included in context for continuity - Configurable threshold (default: 50 messages) ### Git Synchronization Backup and sync conversations across devices: - **Export Format**: Markdown files for human readability - **Auto-Sync Options**: - On app start (pull + import only) - On idle (configurable timeout) - After goodbye phrases ("bye", "thanks", "goodbye") - On model switch - On app quit - Minimum message count threshold - **Manual Sync**: One-click full sync (export + pull + push) ### Email Handler AI-powered email auto-responder: - **Monitoring**: IMAP polling every 30 seconds - **Filtering**: Subject identifier (e.g., `[JARVIS]`) - **Processing**: AI generates contextual responses - **Sending**: SMTP with TLS (port 465 recommended) - **Tracking**: Email log with success/error status - **Security**: AES-256-GCM encrypted credentials ## Troubleshooting ### Common Issues **API Connection Errors:** - Verify API keys in Settings → General - Check internet connection - Ensure provider is not experiencing outages **MCP Not Working:** - Verify folder permissions in Settings → MCP - Check allowed folders list - Ensure files are not in .gitignore (if enabled) **Git Sync Errors:** - Verify repository URL and credentials - Check if repository is initialized (clone first) - Ensure proper network access to Git server - Use access token instead of password for GitHub **Email Handler Issues:** - Verify IMAP/SMTP settings and credentials - Use port 465 for SMTP (direct TLS recommended) - Check subject identifier matches exactly (case-sensitive) - Review email logs in Settings → Email → View Email Log **Embedding Errors:** - Configure API key for OpenAI, OpenRouter, or Google - Check Settings → Advanced → Semantic Search - Verify embedding provider is selected ## Roadmap - [x] Vector index for faster semantic search (sqlite-vss) - [x] Reasoning / thinking tokens (streamed live, collapsible) - [x] Localization (Norwegian Bokmål, Swedish, Danish, German) - [x] iCloud Backup (settings export/restore) - [x] Bash execution with per-command approval - [ ] SOUL.md / USER.md — living identity documents injected into system prompt - [ ] Parallel research agents (read-only, concurrent) - [ ] Local embeddings (sentence-transformers, $0 cost) - [ ] Multi-modal conversation export (PDF, HTML) - [ ] iOS companion app with CloudKit sync ## License oAI is free software licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. This means you are free to use, study, modify, and distribute oAI, but any modified version you run as a network service must also be made available as free software under the same license. See [LICENSE](LICENSE) for the full license text, or visit [gnu.org/licenses/agpl-3.0](https://www.gnu.org/licenses/agpl-3.0.html). ## Development See [DEVELOPMENT.md](DEVELOPMENT.md) for project structure, build scripts, database schema, and contribution guidelines. ## Author **Rune Olsen** - Website: https://mac.oai.pm - Blog: [https://blog.rune.pm](https://blog.rune.pm) - Gitlab.pm: [@rune](https://gitlab.pm/rune) ## Contributing Contributions are welcome! See [DEVELOPMENT.md](DEVELOPMENT.md) for build instructions and project structure. --- **⭐ Star this project if you find it useful!** **🐛 Found a bug?** [Open an issue](https://gitlab.pm/rune/oai-swift/issues/new)