Added a lot of functionality. Bugfixes and changes
This commit is contained in:
@@ -31,6 +31,8 @@
|
||||
<li><a href="#online-mode">Online Mode (Web Search)</a></li>
|
||||
<li><a href="#mcp">MCP (File Access)</a></li>
|
||||
<li><a href="#conversations">Managing Conversations</a></li>
|
||||
<li><a href="#git-sync">Git Sync (Backup & Sync)</a></li>
|
||||
<li><a href="#email-handler">Email Handler (AI Assistant)</a></li>
|
||||
<li><a href="#keyboard-shortcuts">Keyboard Shortcuts</a></li>
|
||||
<li><a href="#settings">Settings</a></li>
|
||||
<li><a href="#system-prompts">System Prompts</a></li>
|
||||
@@ -378,6 +380,442 @@
|
||||
<p class="note">Files are saved to your Downloads folder.</p>
|
||||
</section>
|
||||
|
||||
<!-- Git Sync -->
|
||||
<section id="git-sync">
|
||||
<h2>Git Sync (Backup & Sync)</h2>
|
||||
<p>Automatically backup and synchronize your conversations across multiple machines using Git.</p>
|
||||
|
||||
<div class="tip">
|
||||
<strong>💡 What is Git Sync?</strong> Git Sync turns your conversations into markdown files stored in a Git repository. This allows you to backup conversations, sync them across devices, and restore them on new machines.
|
||||
</div>
|
||||
|
||||
<h3>Getting Started</h3>
|
||||
<ol>
|
||||
<li>Create a Git repository on your preferred service:
|
||||
<ul>
|
||||
<li><a href="https://github.com">GitHub</a> (free private repos)</li>
|
||||
<li><a href="https://gitlab.com">GitLab</a> (free private repos)</li>
|
||||
<li><a href="https://gitea.io">Gitea</a> (self-hosted)</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Open Settings (<kbd>⌘,</kbd>) → <strong>Sync</strong> tab</li>
|
||||
<li>Enter your repository URL (e.g., <code>https://github.com/username/oai-sync.git</code>)</li>
|
||||
<li>Choose authentication method:
|
||||
<ul>
|
||||
<li><strong>SSH Key</strong> - Most secure, recommended</li>
|
||||
<li><strong>Username + Password</strong> - Simple but less secure</li>
|
||||
<li><strong>Access Token</strong> - Good balance of security and convenience</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Click <strong>Clone Repository</strong> to initialize</li>
|
||||
</ol>
|
||||
|
||||
<h3>Auto-Save Features</h3>
|
||||
<p>When auto-save is enabled, oAI automatically saves and syncs conversations based on triggers:</p>
|
||||
|
||||
<h4>Auto-Save Triggers</h4>
|
||||
<ul>
|
||||
<li><strong>On Model Switch</strong> - Saves when you change AI models</li>
|
||||
<li><strong>On App Quit</strong> - Saves before oAI closes</li>
|
||||
<li><strong>After Idle Timeout</strong> - Saves after 5 seconds of inactivity</li>
|
||||
</ul>
|
||||
|
||||
<h4>Auto-Save Settings</h4>
|
||||
<ul>
|
||||
<li><strong>Minimum Messages</strong> - Only save conversations with at least N messages (default: 5)</li>
|
||||
<li><strong>Auto-Export</strong> - Export conversations to markdown after save</li>
|
||||
<li><strong>Auto-Commit</strong> - Commit changes to git automatically</li>
|
||||
<li><strong>Auto-Push</strong> - Push commits to remote repository</li>
|
||||
</ul>
|
||||
|
||||
<div class="warning">
|
||||
<strong>⚠️ Multi-Machine Warning:</strong> Running auto-sync on multiple machines simultaneously can cause merge conflicts. Use auto-sync on your primary machine only, or manually sync on others.
|
||||
</div>
|
||||
|
||||
<h3>Manual Sync Operations</h3>
|
||||
<p>Use manual controls for fine-grained sync operations:</p>
|
||||
|
||||
<dl class="commands">
|
||||
<dt>Clone Repository</dt>
|
||||
<dd>Initialize a fresh clone of your remote repository</dd>
|
||||
|
||||
<dt>Export All</dt>
|
||||
<dd>Export all conversations to markdown files (does not commit)</dd>
|
||||
|
||||
<dt>Push</dt>
|
||||
<dd>Export conversations, commit changes, and push to remote</dd>
|
||||
|
||||
<dt>Pull</dt>
|
||||
<dd>Fetch latest changes from remote repository</dd>
|
||||
|
||||
<dt>Import</dt>
|
||||
<dd>Import all conversations from markdown files into the database</dd>
|
||||
</dl>
|
||||
|
||||
<h3>Sync Status Indicators</h3>
|
||||
<p>oAI shows sync status in two places:</p>
|
||||
|
||||
<h4>Header Indicator (Green/Orange/Red Pill)</h4>
|
||||
<ul>
|
||||
<li><strong>🟢 Synced</strong> - Last sync successful</li>
|
||||
<li><strong>🟠 Syncing...</strong> - Sync in progress</li>
|
||||
<li><strong>🔴 Error</strong> - Sync failed (check error message)</li>
|
||||
</ul>
|
||||
|
||||
<h4>Footer Status (Bottom-Left)</h4>
|
||||
<ul>
|
||||
<li><strong>Last Sync: 2m ago</strong> - Shows time since last successful sync</li>
|
||||
<li><strong>Not Synced</strong> - Repository cloned but no sync yet</li>
|
||||
<li><strong>Error With Sync</strong> - Last sync attempt failed</li>
|
||||
</ul>
|
||||
|
||||
<h3>Markdown Export Format</h3>
|
||||
<p>Conversations are exported as markdown files with metadata:</p>
|
||||
<div class="example">
|
||||
<pre><code># Conversation Title
|
||||
|
||||
<strong>ID</strong>: <code>uuid</code>
|
||||
<strong>Created</strong>: 2026-02-13T10:30:00.000Z
|
||||
<strong>Updated</strong>: 2026-02-13T11:45:00.000Z
|
||||
<strong>Primary Model</strong>: gpt-4
|
||||
<strong>Models Used</strong>: gpt-4, claude-3-sonnet
|
||||
|
||||
---
|
||||
|
||||
## User
|
||||
What's the weather like?
|
||||
|
||||
<em>Model: gpt-4 | Tokens: 50 | Cost: $0.0001</em>
|
||||
|
||||
---
|
||||
|
||||
## Assistant
|
||||
The weather is sunny today!
|
||||
|
||||
<em>Model: gpt-4 | Tokens: 120 | Cost: $0.0024</em>
|
||||
|
||||
---</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Model Tracking</h3>
|
||||
<p>Git Sync tracks which AI model generated each message:</p>
|
||||
<ul>
|
||||
<li><strong>Primary Model</strong> - The main model used in the conversation</li>
|
||||
<li><strong>Models Used</strong> - All models that contributed to the conversation</li>
|
||||
<li><strong>Per-Message Model ID</strong> - Each message knows which model created it</li>
|
||||
</ul>
|
||||
|
||||
<p class="note"><strong>Note:</strong> When you import conversations on a new machine, each message retains its original model information. This ensures perfect fidelity when syncing across devices.</p>
|
||||
|
||||
<h3>Repository Structure</h3>
|
||||
<p>Your sync repository is organized as follows:</p>
|
||||
<div class="example">
|
||||
<pre><code>~/Library/Application Support/oAI/sync/
|
||||
├── README.md # Warning about manual edits
|
||||
└── conversations/
|
||||
├── my-first-chat.md
|
||||
├── python-help.md
|
||||
└── project-discussion.md</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Restoring on a New Machine</h3>
|
||||
<p>To restore your conversations on a new Mac:</p>
|
||||
<ol>
|
||||
<li>Install oAI on the new machine</li>
|
||||
<li>Open Settings → Sync tab</li>
|
||||
<li>Enter your repository URL and credentials</li>
|
||||
<li>Click <strong>Clone Repository</strong></li>
|
||||
<li>Click <strong>Import</strong> to restore all conversations</li>
|
||||
<li>Your conversations appear in the Conversations list with original model info intact</li>
|
||||
</ol>
|
||||
|
||||
<h3>Authentication Methods</h3>
|
||||
|
||||
<h4>SSH Key (Recommended)</h4>
|
||||
<p>Most secure option. Generate an SSH key and add it to your Git service:</p>
|
||||
<ol>
|
||||
<li>Generate key: <code>ssh-keygen -t ed25519 -C "oai@yourmac"</code></li>
|
||||
<li>Add to git service (GitHub Settings → SSH Keys)</li>
|
||||
<li>Use SSH URL in oAI: <code>git@github.com:username/repo.git</code></li>
|
||||
</ol>
|
||||
|
||||
<h4>Access Token</h4>
|
||||
<p>Good balance of security and convenience:</p>
|
||||
<ul>
|
||||
<li><strong>GitHub</strong>: Settings → Developer Settings → Personal Access Tokens → Generate new token</li>
|
||||
<li><strong>GitLab</strong>: Settings → Access Tokens → Add new token</li>
|
||||
<li><strong>Permissions needed</strong>: <code>repo</code> (full repository access)</li>
|
||||
</ul>
|
||||
|
||||
<h4>Username + Password</h4>
|
||||
<p>Simple but less secure. Some services require app-specific passwords instead of your main password.</p>
|
||||
|
||||
<h3>Best Practices</h3>
|
||||
<ul>
|
||||
<li><strong>Use Private Repositories</strong> - Your conversations may contain sensitive information</li>
|
||||
<li><strong>Enable Auto-Sync on One Machine</strong> - Avoid conflicts by syncing automatically on your primary Mac only</li>
|
||||
<li><strong>Manual Sync on Others</strong> - Use Pull/Push buttons on secondary machines</li>
|
||||
<li><strong>Regular Backups</strong> - Git history preserves all versions of your conversations</li>
|
||||
<li><strong>Don't Edit Manually</strong> - The README warns against manual edits; always use oAI's sync features</li>
|
||||
</ul>
|
||||
|
||||
<h3>Troubleshooting</h3>
|
||||
|
||||
<h4>Sync Failed (Red Indicator)</h4>
|
||||
<ul>
|
||||
<li>Check your internet connection</li>
|
||||
<li>Verify authentication credentials</li>
|
||||
<li>Ensure repository URL is correct</li>
|
||||
<li>Check footer for detailed error message</li>
|
||||
</ul>
|
||||
|
||||
<h4>Merge Conflicts</h4>
|
||||
<ul>
|
||||
<li>Stop auto-sync on all but one machine</li>
|
||||
<li>Manually resolve conflicts in the git repository</li>
|
||||
<li>Commit and push the resolution</li>
|
||||
<li>Pull on other machines</li>
|
||||
</ul>
|
||||
|
||||
<h4>Import Shows "0 imported, N skipped"</h4>
|
||||
<p>This is normal! It means those conversations already exist in your local database. Import only adds new conversations that aren't already present (detected by unique conversation ID).</p>
|
||||
</section>
|
||||
|
||||
<!-- Email Handler -->
|
||||
<section id="email-handler">
|
||||
<h2>Email Handler (AI Assistant)</h2>
|
||||
<p>Turn oAI into an AI-powered email auto-responder. Monitor an inbox and automatically reply to emails with intelligent, context-aware responses.</p>
|
||||
|
||||
<div class="tip">
|
||||
<strong>💡 Use Cases:</strong> Customer support automation, personal assistant emails, automated FAQ responses, email-based task management.
|
||||
</div>
|
||||
|
||||
<h3>How It Works</h3>
|
||||
<ol>
|
||||
<li><strong>IMAP Monitoring</strong> - oAI polls your inbox every 30 seconds for new emails</li>
|
||||
<li><strong>Subject Filter</strong> - Only emails with your identifier (e.g., <code>[Jarvis]</code>) are processed</li>
|
||||
<li><strong>AI Processing</strong> - Email content is sent to your configured AI model</li>
|
||||
<li><strong>Auto-Reply</strong> - AI-generated response is sent via SMTP</li>
|
||||
<li><strong>Mark as Read</strong> - Processed emails are marked to prevent duplicates</li>
|
||||
</ol>
|
||||
|
||||
<div class="warning">
|
||||
<strong>⚠️ Important:</strong> Email replies are sent automatically! Test thoroughly with a dedicated email account before using with production email.
|
||||
</div>
|
||||
|
||||
<h3>Setting Up Email Handler</h3>
|
||||
<ol>
|
||||
<li>Press <kbd>⌘,</kbd> to open Settings</li>
|
||||
<li>Go to the <strong>Email</strong> tab</li>
|
||||
<li>Enable <strong>Email Handler</strong> toggle</li>
|
||||
<li>Configure server settings:
|
||||
<ul>
|
||||
<li><strong>IMAP Host</strong>: Your incoming mail server (e.g., <code>imap.gmail.com</code>)</li>
|
||||
<li><strong>SMTP Host</strong>: Your outgoing mail server (e.g., <code>smtp.gmail.com</code>)</li>
|
||||
<li><strong>Username</strong>: Your email address</li>
|
||||
<li><strong>Password</strong>: Your email password or app-specific password</li>
|
||||
<li><strong>Ports</strong>: IMAP 993 (TLS), SMTP 465 (recommended) or 587</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Click <strong>Test Connection</strong> to verify settings</li>
|
||||
<li>Set <strong>Subject Identifier</strong> (e.g., <code>[Jarvis]</code>)</li>
|
||||
<li>Select <strong>AI Provider</strong> and <strong>Model</strong> for responses</li>
|
||||
<li>Save settings and restart oAI</li>
|
||||
</ol>
|
||||
|
||||
<div class="note">
|
||||
<strong>Security Note:</strong> All credentials are encrypted using AES-256-GCM and stored securely in your local database.
|
||||
</div>
|
||||
|
||||
<h3>Email Server Settings</h3>
|
||||
|
||||
<h4>Gmail Setup</h4>
|
||||
<ol>
|
||||
<li>Enable IMAP: Gmail Settings → Forwarding and POP/IMAP → Enable IMAP</li>
|
||||
<li>Create App Password: Google Account → Security → 2-Step Verification → App passwords</li>
|
||||
<li>Use settings:
|
||||
<ul>
|
||||
<li>IMAP: <code>imap.gmail.com</code> port 993</li>
|
||||
<li>SMTP: <code>smtp.gmail.com</code> port 465</li>
|
||||
<li>Password: Use the generated app password, not your main password</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<h4>Common IMAP/SMTP Settings</h4>
|
||||
<dl class="commands">
|
||||
<dt>Gmail</dt>
|
||||
<dd>IMAP: imap.gmail.com:993, SMTP: smtp.gmail.com:465</dd>
|
||||
|
||||
<dt>Outlook/Hotmail</dt>
|
||||
<dd>IMAP: outlook.office365.com:993, SMTP: smtp.office365.com:587</dd>
|
||||
|
||||
<dt>iCloud</dt>
|
||||
<dd>IMAP: imap.mail.me.com:993, SMTP: smtp.mail.me.com:587</dd>
|
||||
|
||||
<dt>Self-Hosted (Mailcow)</dt>
|
||||
<dd>IMAP: mail.yourdomain.com:993, SMTP: mail.yourdomain.com:465</dd>
|
||||
</dl>
|
||||
|
||||
<h3>AI Configuration</h3>
|
||||
<p>Configure how the AI generates email responses:</p>
|
||||
<ul>
|
||||
<li><strong>Provider</strong>: Choose which AI provider to use (Anthropic, OpenRouter, etc.)</li>
|
||||
<li><strong>Model</strong>: Select the AI model (Claude Haiku for fast responses, Sonnet for quality)</li>
|
||||
<li><strong>Max Tokens</strong>: Limit response length (default: 2000)</li>
|
||||
<li><strong>Online Mode</strong>: Enable if AI should search web for current information</li>
|
||||
<li><strong>System Prompt</strong>: Customize AI's personality and response style (optional)</li>
|
||||
</ul>
|
||||
|
||||
<div class="tip">
|
||||
<strong>💡 Model Recommendations:</strong>
|
||||
<ul>
|
||||
<li><strong>Claude Haiku</strong>: Fast, cost-effective for simple replies</li>
|
||||
<li><strong>Claude Sonnet</strong>: Balanced quality and speed</li>
|
||||
<li><strong>GPT-4</strong>: High quality but slower and more expensive</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<h3>Email Trigger (Subject Identifier)</h3>
|
||||
<p>The subject identifier is a text string that must appear in the email subject for processing. This prevents the AI from replying to all emails.</p>
|
||||
|
||||
<h4>Examples</h4>
|
||||
<ul>
|
||||
<li><code>[Jarvis]</code> - Matches "Question [Jarvis]" or "[Jarvis] Help needed"</li>
|
||||
<li><code>[BOT]</code> - Matches "[BOT] Customer inquiry"</li>
|
||||
<li><code>@AI</code> - Matches "Support request @AI"</li>
|
||||
</ul>
|
||||
|
||||
<div class="warning">
|
||||
<strong>⚠️ Case-Sensitive:</strong> The subject identifier is case-sensitive. <code>[Jarvis]</code> will NOT match <code>[jarvis]</code>.
|
||||
</div>
|
||||
|
||||
<h3>Rate Limiting</h3>
|
||||
<p>Prevent the AI from processing too many emails:</p>
|
||||
<ul>
|
||||
<li><strong>Enable Rate Limit</strong>: Toggle to limit emails processed per hour</li>
|
||||
<li><strong>Emails Per Hour</strong>: Maximum number of emails to process (default: 10)</li>
|
||||
<li>When limit is reached, additional emails are logged as errors</li>
|
||||
</ul>
|
||||
|
||||
<h3>Email Log</h3>
|
||||
<p>Track all processed emails in the Email Log (Settings → Email → View Email Log):</p>
|
||||
<ul>
|
||||
<li><strong>Success</strong>: Emails processed and replied to successfully</li>
|
||||
<li><strong>Error</strong>: Failed processing with error details</li>
|
||||
<li><strong>Timestamp</strong>: When the email was processed</li>
|
||||
<li><strong>Sender</strong>: Who sent the email</li>
|
||||
<li><strong>Subject</strong>: Email subject line</li>
|
||||
</ul>
|
||||
|
||||
<h3>How Responses Are Generated</h3>
|
||||
<p>When an email is detected:</p>
|
||||
<ol>
|
||||
<li>Email content is extracted (sender, subject, body)</li>
|
||||
<li>Subject identifier is removed from the subject line</li>
|
||||
<li>Content is sent to AI with system prompt: "You are an AI email assistant. Respond professionally..."</li>
|
||||
<li>AI generates a plain text + HTML response</li>
|
||||
<li>Reply is sent with proper email headers (In-Reply-To, References for threading)</li>
|
||||
<li>Original email is marked as read</li>
|
||||
</ol>
|
||||
|
||||
<h3>Response Time</h3>
|
||||
<p>Email handler uses IMAP polling (not real-time):</p>
|
||||
<ul>
|
||||
<li><strong>Polling Interval</strong>: 30 seconds</li>
|
||||
<li><strong>Average Latency</strong>: 15-30 seconds from email arrival to reply sent</li>
|
||||
<li><strong>AI Processing</strong>: 2-15 seconds depending on model</li>
|
||||
<li><strong>Total Response Time</strong>: ~20-45 seconds typically</li>
|
||||
</ul>
|
||||
|
||||
<h3>Troubleshooting</h3>
|
||||
|
||||
<h4>Email Not Detected</h4>
|
||||
<ul>
|
||||
<li>Verify subject identifier matches exactly (case-sensitive)</li>
|
||||
<li>Check email is in INBOX (not Spam/Junk)</li>
|
||||
<li>Ensure email handler is enabled in Settings</li>
|
||||
<li>Restart oAI to reinitialize monitoring</li>
|
||||
<li>Check logs: <code>~/Library/Logs/oAI.log</code></li>
|
||||
</ul>
|
||||
|
||||
<h4>Connection Errors</h4>
|
||||
<ul>
|
||||
<li>Verify IMAP/SMTP server addresses are correct</li>
|
||||
<li>Check ports: IMAP 993, SMTP 465 (or 587)</li>
|
||||
<li>Use app-specific password (Gmail, iCloud)</li>
|
||||
<li>Allow "less secure apps" if required by provider</li>
|
||||
<li>Check firewall isn't blocking connections</li>
|
||||
</ul>
|
||||
|
||||
<h4>SMTP TLS Errors</h4>
|
||||
<ul>
|
||||
<li>Use port 465 (direct TLS) instead of 587 (STARTTLS)</li>
|
||||
<li>Port 465 is more reliable with oAI's implementation</li>
|
||||
<li>If only 587 available, contact support</li>
|
||||
</ul>
|
||||
|
||||
<h4>Authentication Failed</h4>
|
||||
<ul>
|
||||
<li>Gmail: Use app password, not main password</li>
|
||||
<li>iCloud: Use app-specific password</li>
|
||||
<li>Outlook: Enable IMAP in account settings</li>
|
||||
<li>Double-check username is your full email address</li>
|
||||
</ul>
|
||||
|
||||
<h4>Duplicate Replies</h4>
|
||||
<ul>
|
||||
<li>Check Email Log for duplicate entries</li>
|
||||
<li>Emails should be marked as read after processing</li>
|
||||
<li>Restart oAI if duplicates persist</li>
|
||||
</ul>
|
||||
|
||||
<h3>Best Practices</h3>
|
||||
<ul>
|
||||
<li><strong>Dedicated Email</strong>: Use a separate email account for AI automation</li>
|
||||
<li><strong>Test First</strong>: Send test emails and verify responses before production use</li>
|
||||
<li><strong>Monitor Email Log</strong>: Regularly check for errors or unexpected behavior</li>
|
||||
<li><strong>Rate Limits</strong>: Enable rate limiting to prevent excessive API costs</li>
|
||||
<li><strong>System Prompt</strong>: Customize the AI's response style with a custom system prompt</li>
|
||||
<li><strong>Privacy</strong>: Don't use with emails containing sensitive information</li>
|
||||
<li><strong>Backup</strong>: Keep copies of important emails; AI responses are automated</li>
|
||||
</ul>
|
||||
|
||||
<h3>Example Workflow</h3>
|
||||
<div class="example">
|
||||
<p><strong>Incoming Email:</strong></p>
|
||||
<pre><code>From: customer@example.com
|
||||
To: support@yourcompany.com
|
||||
Subject: [Jarvis] Product question
|
||||
|
||||
Hi, what are your shipping options?</code></pre>
|
||||
|
||||
<p><strong>AI Response (15-30 seconds later):</strong></p>
|
||||
<pre><code>From: support@yourcompany.com
|
||||
To: customer@example.com
|
||||
Subject: Re: [Jarvis] Product question
|
||||
|
||||
Hello,
|
||||
|
||||
Thank you for reaching out! We offer several shipping options:
|
||||
|
||||
1. Standard shipping (5-7 business days): Free on orders over $50
|
||||
2. Express shipping (2-3 business days): $15
|
||||
3. Next-day delivery: $25
|
||||
|
||||
All orders are processed within 24 hours. You can track your shipment once it ships.
|
||||
|
||||
Is there anything else I can help you with?
|
||||
|
||||
Best regards,
|
||||
AI Assistant</code></pre>
|
||||
</div>
|
||||
|
||||
<div class="note">
|
||||
<strong>Technical Details:</strong> Email handler uses pure Swift with Apple's Network framework. No external dependencies. Credentials encrypted with AES-256-GCM. Source available on GitLab.
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Keyboard Shortcuts -->
|
||||
<section id="keyboard-shortcuts">
|
||||
<h2>Keyboard Shortcuts</h2>
|
||||
|
||||
Reference in New Issue
Block a user