oAI

A powerful native macOS AI chat application with support for multiple providers, advanced memory management, and seamless Git synchronization.

Features

🤖 Multi-Provider Support

• OpenAI - GPT models with native API support
• Anthropic - Claude models with OAuth integration
• OpenRouter - Access to 300+ AI models from multiple providers
• Google - Gemini models with native integration
• 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.)
• 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

🔧 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

📧 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

Installation

Not available.

Requirements

• macOS 14.0+
• Xcode 15.0+
• Swift 5.9+

Configuration

API Keys

Add your API keys in Settings (⌘,) → General tab:

• OpenAI - Get from OpenAI Platform
• Anthropic - Get from Anthropic Console or use OAuth
• OpenRouter - Get from OpenRouter Keys
• Google - Get from Google AI Studio
• Ollama - Base URL (default: http://localhost:11434)

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)

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 <name> - Save current conversation
• /load or /list - List and load saved conversations (⌘L)
• /delete <name> - Delete a saved conversation
• /export <md|json> [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 <on|off> - Toggle conversation memory
• /online <on|off> - Toggle online/web search mode
• /mcp <on|off|status|add|remove|list|write> - Manage MCP filesystem access

MCP (Model Context Protocol)

• /mcp add <path> - Grant AI access to a folder
• /mcp remove <index|path> - Revoke folder access
• /mcp list - Show allowed folders
• /mcp write <on|off> - 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

Development

Project Structure

oAI/
├── Models/              # Data models
│   ├── Message.swift           # Chat message model
│   ├── Conversation.swift      # Saved conversation model
│   ├── ModelInfo.swift         # AI model metadata
│   └── Settings.swift          # App settings enums
│
├── Views/               # SwiftUI views
│   ├── Main/                   # Primary UI components
│   │   ├── ChatView.swift      # Main chat interface
│   │   ├── MessageRow.swift    # Individual message display
│   │   ├── InputBar.swift      # Message input with commands
│   │   ├── HeaderView.swift    # Top bar (provider/model/status)
│   │   └── FooterView.swift    # Bottom stats bar
│   │
│   └── Screens/                # Modal/sheet views
│       ├── SettingsView.swift  # Settings with tabs
│       ├── ModelSelectorView.swift
│       ├── ConversationListView.swift
│       └── HelpView.swift
│
├── ViewModels/          # Observable view models
│   └── ChatViewModel.swift     # Main chat logic & state
│
├── Providers/           # AI provider implementations
│   ├── Provider.swift          # Protocol definition
│   ├── OpenRouterProvider.swift
│   ├── AnthropicProvider.swift
│   ├── OpenAIProvider.swift
│   └── OllamaProvider.swift
│
├── Services/            # Business logic & data
│   ├── DatabaseService.swift   # SQLite operations (GRDB)
│   ├── SettingsService.swift   # Settings persistence
│   ├── ProviderRegistry.swift  # AI provider management
│   ├── MCPService.swift        # File access (MCP)
│   ├── WebSearchService.swift  # DuckDuckGo/Google search
│   ├── GitSyncService.swift    # Git synchronization
│   ├── ContextSelectionService.swift  # Smart context
│   ├── EmbeddingService.swift  # Semantic search
│   ├── EmailService.swift      # Email monitoring (IMAP)
│   └── EmailHandlerService.swift  # Email AI responder
│
└── Resources/
    └── oAI.help/               # macOS Help Book

Key Technologies

• SwiftUI - Modern declarative UI framework
• GRDB - SQLite database wrapper for persistence
• MarkdownUI - Markdown rendering with syntax highlighting
• os.Logger - Native logging framework
• Network Framework - Pure Swift IMAP/SMTP implementation
• Security Framework - Keychain and encryption services

Database Schema

Conversations: id, name, createdAt, updatedAt Messages: id, conversationId, role, content, tokens, cost, timestamp Message Metadata: message_id, importance_score, user_starred, summary Message Embeddings: message_id, embedding (BLOB), model, dimension Conversation Summaries: id, conversationId, startIndex, endIndex, summary Email Logs: id, sender, subject, status, timestamp

Building & Debugging

Build Commands:

# Clean build
xcodebuild clean -scheme oAI

# Build
xcodebuild -scheme oAI -configuration Debug

# Run tests
xcodebuild test -scheme oAI

Logs Location:

~/Library/Logs/oAI.log

Database Location:

~/Library/Application Support/oAI/oai_conversations.db

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

Performance Notes

• Context Selection: 50-80% token reduction for long conversations
• Semantic Search: ~$0.02-0.15/month for heavy users
• Conversation Export: Markdown format for human readability
• Database: Indexed queries for fast conversation retrieval
• Streaming: Efficient memory usage with AsyncThrowingStream

Roadmap

• Vector index for faster semantic search (sqlite-vss)
• Local embeddings (sentence-transformers, $0 cost)
• Conversation clustering and recommendations
• Multi-modal conversation export (PDF, HTML)
• Plugin system for custom tools
• iOS companion app with CloudKit sync

License

MIT License - See LICENSE for details.

Author

Rune Olsen

• Website: https://blog.rune.pm
• GitHub: @yourusername

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• Code follows Swift style guidelines
• All tests pass
• Documentation is updated
• Commit messages are descriptive

Acknowledgments

• MarkdownUI - Excellent markdown rendering library
• GRDB - Robust SQLite wrapper for Swift
• Anthropic, OpenAI, OpenRouter - AI API providers
• macOS Community - Inspiration and support

---

⭐ Star this project if you find it useful!

🐛 Found a bug? Open an issue

💡 Have a feature request? Start a discussion