1407 lines
72 KiB
HTML
1407 lines
72 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="AppleTitle" content="oAI Help">
|
|
<meta name="AppleIcon" content="images/icon.png">
|
|
<meta name="description" content="oAI - AI Chat Assistant for macOS">
|
|
<meta name="keywords" content="oAI, AI, chat, assistant, OpenAI, Anthropic, Claude, GPT, commands, help">
|
|
<title>oAI Help</title>
|
|
<link rel="stylesheet" href="styles.css">
|
|
</head>
|
|
<body>
|
|
<div class="container">
|
|
<header>
|
|
<img src="images/icon.png" alt="oAI Icon" class="app-icon">
|
|
<h1>oAI Help</h1>
|
|
<p class="subtitle">AI Chat Assistant for macOS</p>
|
|
</header>
|
|
|
|
<nav class="toc">
|
|
<h2>Contents</h2>
|
|
<ul>
|
|
<li><a href="#getting-started">Getting Started</a></li>
|
|
<li><a href="#providers">AI Providers & API Keys</a></li>
|
|
<li><a href="#models">Selecting Models</a></li>
|
|
<li><a href="#sending-messages">Sending Messages</a></li>
|
|
<li><a href="#file-attachments">File Attachments</a></li>
|
|
<li><a href="#commands">Slash Commands</a></li>
|
|
<li><a href="#memory">Memory & Context</a></li>
|
|
<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="#shortcuts">Shortcuts (Prompt Templates)</a></li>
|
|
<li><a href="#agent-skills">Agent Skills (SKILL.md)</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>
|
|
</ul>
|
|
</nav>
|
|
|
|
<main>
|
|
<!-- Getting Started -->
|
|
<section id="getting-started">
|
|
<h2>Getting Started</h2>
|
|
<p>oAI is a powerful AI chat assistant that connects to multiple AI providers including OpenAI, Anthropic, OpenRouter, and local models via Ollama.</p>
|
|
|
|
<div class="steps">
|
|
<h3>Quick Start</h3>
|
|
<ol>
|
|
<li><strong>Add an API key</strong>: Press <kbd>⌘,</kbd> to open Settings, then add your API key for your preferred provider</li>
|
|
<li><strong>Select a model</strong>: Press <kbd>⌘M</kbd> or type <code>/model</code> to choose an AI model</li>
|
|
<li><strong>Start chatting</strong>: Type your message and press <kbd>Return</kbd> to send</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Tip:</strong> Type <code>/</code> in the message input to see all available commands with autocomplete suggestions.
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Providers -->
|
|
<section id="providers">
|
|
<h2>AI Providers & API Keys</h2>
|
|
<p>oAI supports multiple AI providers. You'll need an API key from at least one provider to use the app.</p>
|
|
|
|
<h3>Supported Providers</h3>
|
|
<ul class="provider-list">
|
|
<li><strong>OpenRouter</strong> - Access to 300+ models through a single API (<a href="https://openrouter.ai">openrouter.ai</a>)</li>
|
|
<li><strong>Anthropic</strong> - Claude models (Opus, Sonnet, Haiku) (<a href="https://console.anthropic.com">console.anthropic.com</a>)</li>
|
|
<li><strong>OpenAI</strong> - GPT-4, GPT-4 Turbo, GPT-3.5 models (<a href="https://platform.openai.com">platform.openai.com</a>)</li>
|
|
<li><strong>Ollama</strong> - Run models locally on your Mac (<a href="https://ollama.ai">ollama.ai</a>)</li>
|
|
</ul>
|
|
|
|
<h3>Adding an API Key</h3>
|
|
<ol>
|
|
<li>Press <kbd>⌘,</kbd> or type <code>/config</code> to open Settings</li>
|
|
<li>Select the <strong>Providers</strong> tab</li>
|
|
<li>Enter your API key for the desired provider</li>
|
|
<li>Click <strong>Save</strong></li>
|
|
</ol>
|
|
|
|
<h3>Switching Providers</h3>
|
|
<p>Use the provider dropdown in the header or type:</p>
|
|
<code class="command">/provider anthropic</code>
|
|
<code class="command">/provider openai</code>
|
|
<code class="command">/provider openrouter</code>
|
|
</section>
|
|
|
|
<!-- Models -->
|
|
<section id="models">
|
|
<h2>Selecting Models</h2>
|
|
<p>Different models have different capabilities, speeds, and costs. Choose the right model for your task.</p>
|
|
|
|
<h3>Opening the Model Selector</h3>
|
|
<ul>
|
|
<li>Press <kbd>⌘M</kbd></li>
|
|
<li>Type <code>/model</code></li>
|
|
<li>Click the model name in the header</li>
|
|
</ul>
|
|
|
|
<h3>Model Information</h3>
|
|
<p>View details about any model:</p>
|
|
<code class="command">/info</code>
|
|
<p class="note">Shows information about the currently selected model including context length, pricing, and capabilities.</p>
|
|
|
|
<h3>Default Model</h3>
|
|
<p>Your selected model is automatically saved and will be restored when you restart the app.</p>
|
|
</section>
|
|
|
|
<!-- Sending Messages -->
|
|
<section id="sending-messages">
|
|
<h2>Sending Messages</h2>
|
|
|
|
<h3>Basic Usage</h3>
|
|
<ul>
|
|
<li>Type your message in the input field</li>
|
|
<li>Press <kbd>Return</kbd> to send (single-line messages)</li>
|
|
<li>Press <kbd>⇧Return</kbd> to add a new line without sending</li>
|
|
</ul>
|
|
|
|
<h3>During Generation</h3>
|
|
<p>While the AI is responding:</p>
|
|
<ul>
|
|
<li>Press <kbd>Esc</kbd> to cancel generation</li>
|
|
<li>Click the <strong>Stop</strong> button (red circle)</li>
|
|
<li>Cancelled responses show a <strong>⚠️ interrupted</strong> indicator</li>
|
|
</ul>
|
|
|
|
<h3>Retrying Messages</h3>
|
|
<p>If you're not satisfied with a response:</p>
|
|
<code class="command">/retry</code>
|
|
<p class="note">Resends your last message to generate a new response.</p>
|
|
</section>
|
|
|
|
<!-- File Attachments -->
|
|
<section id="file-attachments">
|
|
<h2>File Attachments</h2>
|
|
<p>Attach files to your messages for the AI to analyze. Supports images, PDFs, and text files.</p>
|
|
|
|
<h3>Attaching Files</h3>
|
|
<ul>
|
|
<li>Click the <strong>📎 paperclip icon</strong> to browse and select files</li>
|
|
<li>Type <code>@/path/to/file.txt</code> in your message</li>
|
|
<li>Type <code>@~/Documents/image.png</code> for files in your home directory</li>
|
|
</ul>
|
|
|
|
<h3>Supported File Types</h3>
|
|
<ul>
|
|
<li><strong>Images</strong>: PNG, JPEG, GIF, WebP, BMP, SVG (max 10 MB)</li>
|
|
<li><strong>Documents</strong>: PDF (max 10 MB)</li>
|
|
<li><strong>Text</strong>: TXT, code files, logs, etc. (max 50 KB)</li>
|
|
</ul>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Tip:</strong> Large text files are automatically truncated to prevent token limits.
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Commands -->
|
|
<section id="commands">
|
|
<h2>Slash Commands</h2>
|
|
<p>Commands start with <code>/</code> and provide quick access to features. Type <code>/</code> to see suggestions.</p>
|
|
|
|
<h3>Chat Commands</h3>
|
|
<dl class="commands">
|
|
<dt>/history</dt>
|
|
<dd>View command history with timestamps (European format: dd.MM.yyyy). Search by text or date to find previous messages</dd>
|
|
|
|
<dt>/clear</dt>
|
|
<dd>Clear all messages from the current session</dd>
|
|
|
|
<dt>/retry</dt>
|
|
<dd>Retry your last message to get a new response</dd>
|
|
|
|
<dt>/memory on|off</dt>
|
|
<dd>Toggle conversation memory. When off, only your latest message is sent (no conversation history)</dd>
|
|
|
|
<dt>/online on|off</dt>
|
|
<dd>Enable/disable web search. When on, the AI can search the web for current information</dd>
|
|
</dl>
|
|
|
|
<h3>Model & Provider Commands</h3>
|
|
<dl class="commands">
|
|
<dt>/model</dt>
|
|
<dd>Open the model selector</dd>
|
|
|
|
<dt>/provider [name]</dt>
|
|
<dd>Switch AI provider or show current provider</dd>
|
|
|
|
<dt>/info</dt>
|
|
<dd>Display information about the current model</dd>
|
|
|
|
<dt>/credits</dt>
|
|
<dd>Check your account balance (OpenRouter only)</dd>
|
|
</dl>
|
|
|
|
<h3>Conversation Commands</h3>
|
|
<dl class="commands">
|
|
<dt>/save <name></dt>
|
|
<dd>Save the current conversation</dd>
|
|
|
|
<dt>/load</dt>
|
|
<dd>Browse and load a saved conversation</dd>
|
|
|
|
<dt>/list</dt>
|
|
<dd>Show all saved conversations</dd>
|
|
|
|
<dt>/delete <name></dt>
|
|
<dd>Delete a saved conversation</dd>
|
|
|
|
<dt>/export md|json</dt>
|
|
<dd>Export conversation as Markdown or JSON</dd>
|
|
</dl>
|
|
|
|
<h3>MCP Commands</h3>
|
|
<dl class="commands">
|
|
<dt>/mcp on|off</dt>
|
|
<dd>Enable/disable file access for the AI</dd>
|
|
|
|
<dt>/mcp add <path></dt>
|
|
<dd>Grant AI access to a folder</dd>
|
|
|
|
<dt>/mcp remove <path></dt>
|
|
<dd>Revoke AI access to a folder</dd>
|
|
|
|
<dt>/mcp list</dt>
|
|
<dd>Show all accessible folders</dd>
|
|
|
|
<dt>/mcp status</dt>
|
|
<dd>Display MCP status and permissions</dd>
|
|
|
|
<dt>/mcp write on|off</dt>
|
|
<dd>Enable/disable write permissions</dd>
|
|
</dl>
|
|
|
|
<h3>Shortcuts & Skills Commands</h3>
|
|
<dl class="commands">
|
|
<dt>/shortcuts</dt>
|
|
<dd>Open the Shortcuts manager to create, edit, and manage your custom prompt template commands</dd>
|
|
|
|
<dt>/skills</dt>
|
|
<dd>Open the Agent Skills manager to install and manage SKILL.md-style behavioral instruction files</dd>
|
|
|
|
<dt>/<your-command></dt>
|
|
<dd>Run any shortcut you've created. Example: <code>/summarize</code> to run your "Summarize" shortcut</dd>
|
|
</dl>
|
|
|
|
<h3>Settings Commands</h3>
|
|
<dl class="commands">
|
|
<dt>/config, /settings</dt>
|
|
<dd>Open the settings panel</dd>
|
|
|
|
<dt>/stats</dt>
|
|
<dd>Show session statistics (messages, tokens, cost)</dd>
|
|
</dl>
|
|
</section>
|
|
|
|
<!-- Memory -->
|
|
<section id="memory">
|
|
<h2>Memory & Context</h2>
|
|
<p>oAI features an enhanced memory and context system with intelligent message selection, semantic search, and automatic summarization.</p>
|
|
|
|
<h3>Basic Memory Control</h3>
|
|
<p>Control whether the AI remembers previous messages:</p>
|
|
<code class="command">/memory on</code>
|
|
<code class="command">/memory off</code>
|
|
|
|
<div class="note">
|
|
<strong>Note:</strong> Memory state is shown in the header with a badge when enabled.
|
|
</div>
|
|
|
|
<h3>Smart Context Selection</h3>
|
|
<p>When enabled, oAI intelligently selects which messages to send instead of sending all history. This reduces token usage by 50-80% while maintaining context quality.</p>
|
|
|
|
<h4>How It Works</h4>
|
|
<ul>
|
|
<li>Always includes the last 10 messages (recent context)</li>
|
|
<li>Includes starred messages (user-marked as important)</li>
|
|
<li>Includes high-importance messages (high cost, detailed content)</li>
|
|
<li>Respects model context limits</li>
|
|
</ul>
|
|
|
|
<h4>Enabling Smart Context</h4>
|
|
<ol>
|
|
<li>Go to Settings → Advanced</li>
|
|
<li>Enable "Smart Context Selection"</li>
|
|
<li>Set max context tokens (default: 100,000)</li>
|
|
</ol>
|
|
|
|
<h3>Message Starring</h3>
|
|
<p>Star important messages to always include them in context, regardless of age:</p>
|
|
<ol>
|
|
<li>Hover over any user or assistant message</li>
|
|
<li>Click the star icon (⭐) in the header</li>
|
|
<li>Starred messages show a filled yellow star</li>
|
|
</ol>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Tip:</strong> Star key decisions, important information, or context you want the AI to always remember.
|
|
</div>
|
|
|
|
<h3>Semantic Search</h3>
|
|
<p>Find conversations by meaning, not just keywords. Powered by AI embeddings.</p>
|
|
|
|
<h4>Setup</h4>
|
|
<ol>
|
|
<li>Go to Settings → Advanced → Semantic Search</li>
|
|
<li>Enable "Enable Embeddings"</li>
|
|
<li>Requires API key for OpenAI, OpenRouter, or Google</li>
|
|
<li>Choose your preferred embedding provider and model</li>
|
|
<li>Click "Embed All Conversations" (one-time, ~$0.04 for 10k messages)</li>
|
|
</ol>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Provider Priority:</strong> If you have multiple API keys configured, the app uses OpenAI → OpenRouter → Google in that order. You can override this by selecting a specific model in settings.
|
|
</div>
|
|
|
|
<h4>Using Semantic Search</h4>
|
|
<ol>
|
|
<li>Open conversation list (<code>/list</code> or <kbd>⌘L</kbd>)</li>
|
|
<li>Type your search query</li>
|
|
<li>Toggle "Semantic" switch ON</li>
|
|
<li>Results ranked by meaning, not keyword matching</li>
|
|
</ol>
|
|
|
|
<div class="example">
|
|
<strong>Example:</strong> Search for "login security methods" to find a conversation titled "Morning Chat" that discussed authentication, even though the title doesn't contain those words.
|
|
</div>
|
|
|
|
<h3>Progressive Summarization</h3>
|
|
<p>For very long conversations, oAI automatically summarizes older messages to save tokens while preserving context.</p>
|
|
|
|
<h4>How It Works</h4>
|
|
<ul>
|
|
<li>When conversation exceeds threshold (default: 50 messages)</li>
|
|
<li>Older messages (0-30) are summarized into 2-3 paragraphs</li>
|
|
<li>Summary focuses on key topics, decisions, and information</li>
|
|
<li>Recent messages (last 20) always sent in full</li>
|
|
<li>Summaries included in system prompt for context</li>
|
|
</ul>
|
|
|
|
<h4>Enabling Summarization</h4>
|
|
<ol>
|
|
<li>Go to Settings → Advanced → Progressive Summarization</li>
|
|
<li>Enable "Enable Summarization"</li>
|
|
<li>Set message threshold (default: 50)</li>
|
|
</ol>
|
|
|
|
<div class="note">
|
|
<strong>Cost:</strong> Each summary costs ~$0.001. For a heavy user (10 summaries/month), this is ~$0.01/month.
|
|
</div>
|
|
|
|
<h3>All Three Together</h3>
|
|
<p>When all features are enabled:</p>
|
|
<ol>
|
|
<li><strong>Smart Context Selection</strong>: Picks relevant messages (15-20 from 100)</li>
|
|
<li><strong>Progressive Summarization</strong>: Provides summaries of excluded old messages</li>
|
|
<li><strong>Semantic Search</strong>: Find conversations by meaning</li>
|
|
</ol>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Result:</strong> 50-80% token reduction, better context quality, and ability to handle 100+ message conversations efficiently.
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Online Mode -->
|
|
<section id="online-mode">
|
|
<h2>Online Mode (Web Search)</h2>
|
|
<p>Enable the AI to search the web for current information before responding.</p>
|
|
|
|
<h3>When to Use Online Mode</h3>
|
|
<ul>
|
|
<li>Questions about current events</li>
|
|
<li>Recent news or updates</li>
|
|
<li>Real-time data (weather, stocks, etc.)</li>
|
|
<li>Information beyond the AI's training cutoff</li>
|
|
</ul>
|
|
|
|
<h3>Enabling Online Mode</h3>
|
|
<code class="command">/online on</code>
|
|
|
|
<h3>How It Works</h3>
|
|
<p>When online mode is enabled:</p>
|
|
<ol>
|
|
<li>Your question is used to search the web</li>
|
|
<li>Relevant results are retrieved</li>
|
|
<li>Search results are added to your message context</li>
|
|
<li>The AI uses the web results to inform its response</li>
|
|
</ol>
|
|
|
|
<div class="note">
|
|
<strong>Note:</strong> Online mode is shown in the input bar with a 🌐 badge when active.
|
|
</div>
|
|
</section>
|
|
|
|
<!-- MCP -->
|
|
<section id="mcp">
|
|
<h2>MCP (File Access)</h2>
|
|
<p>MCP (Model Context Protocol) allows the AI to access, read, and optionally modify files on your computer.</p>
|
|
|
|
<div class="warning">
|
|
<strong>⚠️ Security:</strong> Only grant access to folders you trust the AI to work with. Review permissions carefully.
|
|
</div>
|
|
|
|
<h3>Setting Up MCP</h3>
|
|
<ol>
|
|
<li>Enable MCP: <code>/mcp on</code></li>
|
|
<li>Add a folder: <code>/mcp add ~/Projects/myapp</code></li>
|
|
<li>Ask the AI questions about your files</li>
|
|
</ol>
|
|
|
|
<h3>What the AI Can Do</h3>
|
|
<p><strong>Read permissions (always enabled when MCP is on):</strong></p>
|
|
<ul>
|
|
<li>Read file contents</li>
|
|
<li>List directory contents</li>
|
|
<li>Search for files</li>
|
|
<li>Get file information (size, modified date, etc.)</li>
|
|
</ul>
|
|
|
|
<p><strong>Write permissions (optional, disabled by default):</strong></p>
|
|
<ul>
|
|
<li>Write and edit files</li>
|
|
<li>Create new files</li>
|
|
<li>Delete files</li>
|
|
<li>Create directories</li>
|
|
<li>Move and copy files</li>
|
|
</ul>
|
|
|
|
<h3>Managing Permissions</h3>
|
|
<p>Toggle all write permissions:</p>
|
|
<code class="command">/mcp write on</code>
|
|
<code class="command">/mcp write off</code>
|
|
|
|
<p>For fine-grained control, open Settings → MCP to enable/disable individual permissions.</p>
|
|
|
|
<h3>Gitignore Respect</h3>
|
|
<p>When enabled in Settings, MCP will ignore files and folders listed in <code>.gitignore</code> files.</p>
|
|
|
|
<h3>Example Usage</h3>
|
|
<div class="example">
|
|
<p><strong>You:</strong> "What files are in my project folder?"</p>
|
|
<p><strong>AI:</strong> <em>(uses MCP to list files)</em> "I found 15 files including src/main.py, README.md..."</p>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Conversations -->
|
|
<section id="conversations">
|
|
<h2>Managing Conversations</h2>
|
|
<p>Save, load, search, and export your chat conversations.</p>
|
|
|
|
<h3>Saving Conversations</h3>
|
|
<code class="command">/save my-project-chat</code>
|
|
<p class="note">Saves all current messages under the specified name.</p>
|
|
|
|
<h3>Loading Conversations</h3>
|
|
<code class="command">/load</code>
|
|
<p class="note">Opens a list of saved conversations. Select one to load.</p>
|
|
|
|
<h3>Viewing Saved Conversations</h3>
|
|
<ul>
|
|
<li>Press <kbd>⌘L</kbd></li>
|
|
<li>Type <code>/list</code></li>
|
|
</ul>
|
|
|
|
<h3>Searching Conversations</h3>
|
|
<p>Two search modes available in the conversation list:</p>
|
|
<ul>
|
|
<li><strong>Keyword Search</strong> (default): Matches conversation titles</li>
|
|
<li><strong>Semantic Search</strong>: Finds conversations by meaning (requires embeddings enabled)</li>
|
|
</ul>
|
|
|
|
<div class="steps">
|
|
<h4>Using Semantic Search</h4>
|
|
<ol>
|
|
<li>Open conversation list (<kbd>⌘L</kbd>)</li>
|
|
<li>Type your search query</li>
|
|
<li>Toggle "Semantic" switch ON</li>
|
|
<li>Results ranked by relevance</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="example">
|
|
<strong>Example:</strong> Search "authentication methods" to find conversations about login security, even if the title is just "Chat 2024-01-15".
|
|
</div>
|
|
|
|
<h3>Deleting Conversations</h3>
|
|
<code class="command">/delete old-chat</code>
|
|
<p class="warning"><strong>Warning:</strong> This action cannot be undone.</p>
|
|
|
|
<h3>Bulk Delete</h3>
|
|
<p>In the conversation list:</p>
|
|
<ol>
|
|
<li>Click "Select" button</li>
|
|
<li>Click conversations to select (checkbox appears)</li>
|
|
<li>Click "Delete (N)" button</li>
|
|
</ol>
|
|
|
|
<h3>Exporting Conversations</h3>
|
|
<p>Export to Markdown or JSON format:</p>
|
|
<code class="command">/export md</code>
|
|
<code class="command">/export json</code>
|
|
<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 App Start</strong> - Pulls and imports changes when oAI launches (no push)</li>
|
|
<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>
|
|
|
|
<!-- Shortcuts -->
|
|
<section id="shortcuts">
|
|
<h2>Shortcuts (Prompt Templates)</h2>
|
|
<p>Shortcuts are personal slash commands you define yourself. Each shortcut expands to a prompt template and can optionally ask for input. Think of them as saved prompts with custom command names.</p>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Example:</strong> Create a <code>/summarize</code> shortcut that sends "Please summarize the following text concisely:\n\n{{input}}" — then just type <code>/summarize</code> and paste any text after it.
|
|
</div>
|
|
|
|
<h3>Creating a Shortcut</h3>
|
|
<ol>
|
|
<li>Type <code>/shortcuts</code> or go to Settings → Shortcuts tab</li>
|
|
<li>Click <strong>New Shortcut</strong></li>
|
|
<li>Set a command (e.g. <code>/summarize</code>)</li>
|
|
<li>Add a short description shown in the dropdown</li>
|
|
<li>Write your prompt template</li>
|
|
<li>Click <strong>Save</strong></li>
|
|
</ol>
|
|
|
|
<h3>Using {{input}} Placeholder</h3>
|
|
<p>If your template contains <code>{{input}}</code>, the AI waits for you to type something after the command. Your text replaces <code>{{input}}</code> before sending.</p>
|
|
|
|
<div class="example">
|
|
<strong>With {{input}}:</strong>
|
|
<pre><code>Command: /translate-no
|
|
Template: Translate the following text to Norwegian:\n\n{{input}}
|
|
|
|
Usage: /translate-no Hello, how are you today?
|
|
→ Sends: "Translate the following text to Norwegian:\n\nHello, how are you today?"</code></pre>
|
|
</div>
|
|
|
|
<p>If your template has <strong>no</strong> <code>{{input}}</code>, the shortcut executes immediately when selected — no extra input needed.</p>
|
|
|
|
<div class="example">
|
|
<strong>Without {{input}}:</strong>
|
|
<pre><code>Command: /hello
|
|
Template: Say hello in 5 different languages with a brief cultural note for each.
|
|
|
|
Usage: Type /hello → executes immediately</code></pre>
|
|
</div>
|
|
|
|
<h3>Shortcuts in the Command Dropdown</h3>
|
|
<p>Your shortcuts appear in the <code>/</code> dropdown with a <strong>⚡</strong> prefix. Type the first letters of your command to filter them.</p>
|
|
|
|
<h3>More Shortcut Examples</h3>
|
|
<div class="example">
|
|
<pre><code>/roast "Give me a light-hearted roast of this text: {{input}}"
|
|
/eli5 "Explain {{input}} as if I were 5 years old"
|
|
/debug "Find the bug in this code and explain the fix:\n\n{{input}}"
|
|
/tweet "Rewrite this as a punchy tweet under 280 chars: {{input}}"
|
|
/standup "Based on these notes, write a daily standup update: {{input}}"</code></pre>
|
|
</div>
|
|
|
|
<h3>Import & Export</h3>
|
|
<ul>
|
|
<li><strong>Export All</strong> — saves all shortcuts as <code>shortcuts.json</code> in Downloads</li>
|
|
<li><strong>Import</strong> — load shortcuts from a JSON file (single shortcut or pack)</li>
|
|
<li>When importing a duplicate command, you can choose: <strong>Replace</strong>, <strong>Keep Both</strong>, or <strong>Skip</strong></li>
|
|
</ul>
|
|
</section>
|
|
|
|
<!-- Agent Skills -->
|
|
<section id="agent-skills">
|
|
<h2>Agent Skills (SKILL.md)</h2>
|
|
<p>Agent Skills are markdown instruction files that teach the AI how to behave. Active skills are automatically injected into the system prompt for every conversation — the AI reads them and applies the instructions when relevant.</p>
|
|
|
|
<p>Skills follow the <strong>SKILL.md open standard</strong>, making them compatible with a growing ecosystem of skill marketplaces and community collections.</p>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Example:</strong> Install a "Code Review" skill and the AI will automatically apply code review best practices whenever you share code — no need to ask every time.
|
|
</div>
|
|
|
|
<h3>Installing a Skill</h3>
|
|
<ol>
|
|
<li>Type <code>/skills</code> or go to Settings → Skills tab</li>
|
|
<li>Click <strong>Import</strong> to load a <code>.md</code> file or a <code>.zip</code> skill bundle, <em>or</em></li>
|
|
<li>Click <strong>New Skill</strong> to write your own from scratch</li>
|
|
<li>Toggle the skill <strong>Active</strong> to inject it into the system prompt</li>
|
|
</ol>
|
|
|
|
<h3>SKILL.md Format</h3>
|
|
<p>A skill is a plain Markdown file. The first <code># Heading</code> becomes the skill name. Write instructions in natural language — the AI decides when to apply them.</p>
|
|
|
|
<div class="example">
|
|
<pre><code># Security Auditor
|
|
|
|
When reviewing code, always:
|
|
- Check for injection vulnerabilities (SQL, command, XSS)
|
|
- Look for insecure storage of credentials or secrets
|
|
- Verify authentication and authorization logic
|
|
- Suggest specific fixes, not just observations
|
|
- Rate severity: Critical / High / Medium / Low</code></pre>
|
|
</div>
|
|
|
|
<div class="example">
|
|
<pre><code># Norwegian Translator
|
|
|
|
Whenever the user asks you to translate something, translate it to Norwegian Bokmål.
|
|
- Maintain the original tone and register
|
|
- Keep technical terms in English unless there is a well-established Norwegian equivalent
|
|
- If the text is already in Norwegian, translate it to English instead</code></pre>
|
|
</div>
|
|
|
|
<h3>Writing Your Own Skills</h3>
|
|
<ul>
|
|
<li>Start with a <code># Title</code> — this becomes the skill name in the list</li>
|
|
<li>Use bullet points for rules and guidelines</li>
|
|
<li>Be specific: "always check X" is better than "be careful with X"</li>
|
|
<li>Keep skills focused on one area — create multiple skills rather than one huge one</li>
|
|
<li>The AI reads all active skills before responding — shorter, clearer skills work better</li>
|
|
</ul>
|
|
|
|
<h3>How Skills Are Applied</h3>
|
|
<p>Active skills are appended to the system prompt under an <strong>"Installed Skills"</strong> section. The AI sees them with every message and applies relevant guidance automatically. You can toggle skills on/off without deleting them.</p>
|
|
|
|
<h3>Skill Support Files</h3>
|
|
<p>Each skill can have data files attached — JSON, YAML, CSV, TXT, or any plain-text format. When a skill is active, its files are injected into the system prompt right after the skill's markdown content, so the AI can read and reason over them.</p>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Example use cases:</strong>
|
|
<ul>
|
|
<li><code>news_sources.json</code> — a list of URLs for a "Daily AI News" skill</li>
|
|
<li><code>search_queries.md</code> — template search strings for a research skill</li>
|
|
<li><code>output_templates.md</code> — report formats for a writing skill</li>
|
|
<li><code>config.yaml</code> — parameters a skill should follow</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<h4>Adding Files to a Skill</h4>
|
|
<ol>
|
|
<li>Open the skill editor (click <strong>Edit</strong> on any skill)</li>
|
|
<li>Scroll to the <strong>Files</strong> section at the bottom</li>
|
|
<li>Click <strong>Add File</strong> and select one or more text files</li>
|
|
<li>Files appear in a list with name and size</li>
|
|
<li>Click the trash icon next to any file to remove it</li>
|
|
</ol>
|
|
|
|
<h4>How Files Are Injected</h4>
|
|
<p>In the system prompt, each file is included as a labelled fenced code block immediately after the skill's instructions:</p>
|
|
<div class="example">
|
|
<pre><code>### Daily AI News
|
|
|
|
[skill instructions here]
|
|
|
|
**Skill Data Files:**
|
|
|
|
**news_sources.json:**
|
|
```json
|
|
{ "sources": [...] }
|
|
```
|
|
|
|
**search_queries.md:**
|
|
```md
|
|
...
|
|
```</code></pre>
|
|
</div>
|
|
|
|
<div class="warning">
|
|
<strong>⚠️ Token budget:</strong> Large files inflate the system prompt. A warning appears in the editor if any file exceeds 200 KB. For very large datasets, consider summarizing or splitting the data.
|
|
</div>
|
|
|
|
<h4>File Storage</h4>
|
|
<p>Files are stored locally at:</p>
|
|
<div class="example">
|
|
<pre><code>~/Library/Application Support/oAI/skills/<skill-uuid>/
|
|
├── news_sources.json
|
|
└── search_queries.md</code></pre>
|
|
</div>
|
|
<p>Deleting a skill also deletes its file directory automatically.</p>
|
|
|
|
<h3>Import & Export</h3>
|
|
|
|
<h4>Importing</h4>
|
|
<p>Click <strong>Import</strong> in the Skills manager. You can select:</p>
|
|
<ul>
|
|
<li><strong><code>.md</code> file</strong> — plain SKILL.md-format file. The <code>#</code> heading becomes the skill name</li>
|
|
<li><strong><code>.zip</code> bundle</strong> — a skill with attached data files. The archive should contain a <code>skill.md</code> and any number of data files (in any directory structure — they are flattened into the skill's file directory)</li>
|
|
</ul>
|
|
<p>If a skill with the same name already exists, it is replaced. Data files from a zip are merged into the existing skill's directory.</p>
|
|
|
|
<h4>Exporting</h4>
|
|
<ul>
|
|
<li><strong>Export (single skill)</strong> — click the upload icon on a skill row:
|
|
<ul>
|
|
<li>Skill with no files → exports as <code>skill-name.md</code> to Downloads</li>
|
|
<li>Skill with files → exports as <code>skill-name.zip</code> containing <code>skill.md</code> + all data files</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Export All</strong> — exports every skill using the same logic (each becomes either <code>.md</code> or <code>.zip</code>)</li>
|
|
</ul>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Sharing skills:</strong> Zip bundles are the recommended format for sharing skills that include reference data — import the <code>.zip</code> directly on another machine to restore both the instructions and all attached files.
|
|
</div>
|
|
|
|
<h3>Finding Skills to Download</h3>
|
|
<p>The SKILL.md community has produced hundreds of ready-made skills you can import directly:</p>
|
|
<ul>
|
|
<li><a href="https://skill0.io/" target="_blank">skill0.io</a> — The original SKILL.md marketplace</li>
|
|
<li><a href="https://skillsmp.com" target="_blank">skillsmp.com</a> — Agent Skills Marketplace</li>
|
|
<li><a href="https://agent-skills.md" target="_blank">agent-skills.md</a> — Community skill directory</li>
|
|
<li><a href="https://github.com/anthropics/skills" target="_blank">github.com/anthropics/skills</a> — Anthropic's official skill library</li>
|
|
<li><a href="https://skills.sh/" target="_blank">skills.sh</a> — The Agent Skills Directory</li>
|
|
<li><a href="https://agentskills.io/home" target="_blank">agentskills.io</a> — Agent skills overview and search</li>
|
|
<li><a href="https://github.com/heilcheng/awesome-agent-skills" target="_blank">awesome-agent-skills</a> — Curated community list on GitHub</li>
|
|
</ul>
|
|
|
|
<div class="note">
|
|
<strong>Learn more:</strong> Read the <a href="https://www.mintlify.com/blog/skill-md" target="_blank">SKILL.md open standard article</a> to understand the format in depth, or browse the <a href="https://github.com/anthropics/skills" target="_blank">Anthropic skills repository</a> for high-quality examples.
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Keyboard Shortcuts -->
|
|
<section id="keyboard-shortcuts">
|
|
<h2>Keyboard Shortcuts</h2>
|
|
<p>Work faster with these keyboard shortcuts.</p>
|
|
|
|
<h3>General</h3>
|
|
<dl class="shortcuts">
|
|
<dt><kbd>⌘,</kbd></dt>
|
|
<dd>Open Settings</dd>
|
|
|
|
<dt><kbd>⌘/</kbd></dt>
|
|
<dd>Show in-app Help</dd>
|
|
|
|
<dt><kbd>⌘?</kbd></dt>
|
|
<dd>Open this Help (macOS Help)</dd>
|
|
|
|
<dt><kbd>⌘L</kbd></dt>
|
|
<dd>Browse Conversations</dd>
|
|
|
|
<dt><kbd>⌘H</kbd></dt>
|
|
<dd>Command History</dd>
|
|
|
|
<dt><kbd>⌘M</kbd></dt>
|
|
<dd>Model Selector</dd>
|
|
|
|
<dt><kbd>⌘K</kbd></dt>
|
|
<dd>Clear Chat</dd>
|
|
|
|
<dt><kbd>⇧⌘S</kbd></dt>
|
|
<dd>Show Statistics</dd>
|
|
</dl>
|
|
|
|
<h3>Message Input</h3>
|
|
<dl class="shortcuts">
|
|
<dt><kbd>Return</kbd></dt>
|
|
<dd>Send message (single-line messages)</dd>
|
|
|
|
<dt><kbd>⇧Return</kbd></dt>
|
|
<dd>New line (multi-line messages)</dd>
|
|
|
|
<dt><kbd>Esc</kbd></dt>
|
|
<dd>Cancel generation or close command dropdown</dd>
|
|
|
|
<dt><kbd>↑</kbd> <kbd>↓</kbd></dt>
|
|
<dd>Navigate command suggestions (when typing /)</dd>
|
|
|
|
<dt><kbd>Return</kbd></dt>
|
|
<dd>Select highlighted command (when dropdown is open)</dd>
|
|
</dl>
|
|
</section>
|
|
|
|
<!-- Settings -->
|
|
<section id="settings">
|
|
<h2>Settings</h2>
|
|
<p>Customize oAI to your preferences. Press <kbd>⌘,</kbd> to open Settings.</p>
|
|
|
|
<h3>Providers Tab</h3>
|
|
<ul>
|
|
<li>Add and manage API keys for different providers</li>
|
|
<li>Switch between providers</li>
|
|
<li>Set default models</li>
|
|
</ul>
|
|
|
|
<h3>MCP Tab</h3>
|
|
<ul>
|
|
<li>Manage folder access permissions</li>
|
|
<li>Enable/disable write operations</li>
|
|
<li>Configure gitignore respect</li>
|
|
</ul>
|
|
|
|
<h3>Sync Tab</h3>
|
|
<p>Configure Git synchronization for backing up and syncing conversations across devices.</p>
|
|
<ul>
|
|
<li><strong>Repository URL</strong> - Git repository URL (GitHub, GitLab, Gitea, or custom)</li>
|
|
<li><strong>Authentication Method</strong> - Choose SSH, Password, or Access Token</li>
|
|
<li><strong>Credentials</strong> - Enter username/password or access token (encrypted storage)</li>
|
|
<li><strong>Local Path</strong> - Where to clone the repository locally (default: ~/oAI-Sync)</li>
|
|
<li><strong>Auto-Save Settings</strong>:
|
|
<ul>
|
|
<li><strong>Enable Auto-Save</strong> - Automatically sync conversations</li>
|
|
<li><strong>Minimum Messages</strong> - Only sync conversations with at least N messages</li>
|
|
<li><strong>Triggers</strong> - Sync on app start, idle, goodbye phrases, model switch, or app quit</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Manual Sync</strong>:
|
|
<ul>
|
|
<li><strong>Initialize Repository</strong> - Clone repository for first-time setup</li>
|
|
<li><strong>Sync Now</strong> - Full sync (export + pull + import + push)</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Test Connection</strong> - Verify repository credentials and connectivity</li>
|
|
<li><strong>Sync Status</strong> - Shows last sync time, uncommitted changes, and remote status</li>
|
|
</ul>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Tip:</strong> Use access tokens instead of passwords for GitHub (Settings → Developer settings → Personal access tokens). Enable auto-sync on your primary machine only to avoid conflicts.
|
|
</div>
|
|
|
|
<h3>Email Tab</h3>
|
|
<p>Configure AI-powered email auto-responder to automatically reply to incoming emails.</p>
|
|
<ul>
|
|
<li><strong>Enable Email Handler</strong> - Master toggle for email monitoring</li>
|
|
<li><strong>Subject Identifier</strong> - Filter emails by subject (e.g., <code>[JARVIS]</code>, case-sensitive)</li>
|
|
<li><strong>IMAP Settings</strong>:
|
|
<ul>
|
|
<li><strong>Server</strong> - IMAP server address (e.g., imap.gmail.com)</li>
|
|
<li><strong>Port</strong> - IMAP port (default: 993 for TLS)</li>
|
|
<li><strong>Username</strong> - Email account username (encrypted)</li>
|
|
<li><strong>Password</strong> - Email account password (encrypted, may need app-specific password)</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>SMTP Settings</strong>:
|
|
<ul>
|
|
<li><strong>Server</strong> - SMTP server address (e.g., smtp.gmail.com)</li>
|
|
<li><strong>Port</strong> - SMTP port (465 for direct TLS recommended, 587 for STARTTLS)</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>AI Configuration</strong>:
|
|
<ul>
|
|
<li><strong>Provider</strong> - Which AI provider to use for responses</li>
|
|
<li><strong>Model</strong> - Specific model to use</li>
|
|
<li><strong>Max Tokens</strong> - Response length limit</li>
|
|
<li><strong>Enable Online Mode</strong> - Allow AI to search the web for context</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Rate Limiting</strong>:
|
|
<ul>
|
|
<li><strong>Enable Rate Limit</strong> - Prevent excessive email processing</li>
|
|
<li><strong>Max Per Hour</strong> - Maximum emails to process per hour</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Test Connection</strong> - Verify IMAP/SMTP connectivity and credentials</li>
|
|
<li><strong>Email Log</strong> - View history of processed emails with success/error status</li>
|
|
</ul>
|
|
|
|
<div class="warning">
|
|
<strong>⚠️ Security Note:</strong> All email credentials are encrypted with AES-256-GCM. For Gmail, use app-specific passwords (not your main password). Keep your subject identifier private to prevent abuse.
|
|
</div>
|
|
|
|
<h3>Shortcuts Tab</h3>
|
|
<p>Create and manage personal prompt template commands. See <a href="#shortcuts">Shortcuts</a> section for full details.</p>
|
|
|
|
<h3>Skills Tab</h3>
|
|
<p>Manage SKILL.md-style behavioral instruction files injected into the system prompt. See <a href="#agent-skills">Agent Skills</a> section for full details.</p>
|
|
|
|
<h3>Appearance Tab</h3>
|
|
<ul>
|
|
<li>Adjust text sizes for input and dialog</li>
|
|
<li>Customize UI preferences</li>
|
|
</ul>
|
|
|
|
<h3>Advanced Tab</h3>
|
|
<ul>
|
|
<li>Enable/disable streaming responses</li>
|
|
<li>Set maximum tokens (response length limit)</li>
|
|
<li>Adjust temperature (creativity vs focus)</li>
|
|
<li>Configure system prompts (see below)</li>
|
|
<li><strong>Smart Context Selection</strong> - Intelligently select relevant messages to reduce token usage</li>
|
|
<li><strong>Semantic Search</strong> - Enable AI-powered conversation search using embeddings</li>
|
|
<li><strong>Progressive Summarization</strong> - Automatically summarize old portions of long conversations</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<!-- System Prompts -->
|
|
<section id="system-prompts">
|
|
<h2>System Prompts</h2>
|
|
<p>System prompts are instructions that define how the AI should behave and respond. They set the "personality" and guidelines for the AI before it sees any user messages.</p>
|
|
|
|
<div class="tip">
|
|
<strong>📚 Learn More:</strong> For a detailed explanation of system prompts and how they work, see <a href="https://en.wikipedia.org/wiki/Prompt_engineering" target="_blank">Prompt Engineering on Wikipedia</a> or the <a href="https://platform.openai.com/docs/guides/prompt-engineering" target="_blank">OpenAI Prompt Engineering Guide</a>.
|
|
</div>
|
|
|
|
<h3>What Are System Prompts?</h3>
|
|
<p>System prompts are special instructions sent to the AI with every conversation. Unlike your regular messages, system prompts:</p>
|
|
<ul>
|
|
<li>Are invisible to you in the chat interface</li>
|
|
<li>Set behavioral guidelines for the AI</li>
|
|
<li>Establish the AI's role, tone, and constraints</li>
|
|
<li>Are sent automatically with every message</li>
|
|
<li>Help ensure consistent, reliable responses</li>
|
|
</ul>
|
|
|
|
<h3>Default System Prompt</h3>
|
|
<p>oAI includes a carefully crafted default system prompt that emphasizes:</p>
|
|
<ul>
|
|
<li><strong>Accuracy First</strong> - Never invent information or make assumptions</li>
|
|
<li><strong>Ask for Clarification</strong> - Request details when requests are ambiguous</li>
|
|
<li><strong>Honest About Limitations</strong> - Clearly state when it cannot help</li>
|
|
<li><strong>Stay Grounded</strong> - Base responses on facts, not speculation</li>
|
|
<li><strong>Be Direct</strong> - Provide concise, relevant answers</li>
|
|
</ul>
|
|
|
|
<p class="note"><strong>Note:</strong> The default prompt is always active and cannot be disabled. It ensures the AI provides accurate, helpful responses and doesn't fabricate information.</p>
|
|
|
|
<h3>Custom System Prompt</h3>
|
|
<p>You can add your own custom instructions that will be appended to the default prompt. Use custom prompts to:</p>
|
|
<ul>
|
|
<li>Define a specific role (e.g., "You are a Python expert")</li>
|
|
<li>Set output format preferences (e.g., "Always provide code examples")</li>
|
|
<li>Add domain-specific knowledge or context</li>
|
|
<li>Establish tone or communication style</li>
|
|
<li>Create task-specific guidelines</li>
|
|
</ul>
|
|
|
|
<h3>How Prompts Are Combined</h3>
|
|
<p>When you send a message, oAI constructs the complete system prompt like this:</p>
|
|
|
|
<div class="example">
|
|
<p><strong>Complete System Prompt =</strong></p>
|
|
<ol>
|
|
<li>Default Prompt (always included)</li>
|
|
<li>+ Your Custom Prompt (if set)</li>
|
|
<li>+ MCP Instructions (if MCP is enabled)</li>
|
|
<li>+ Active Agent Skills (if any skills are active)</li>
|
|
</ol>
|
|
<p><em>This combined prompt is sent with every message to ensure consistent behavior.</em></p>
|
|
</div>
|
|
|
|
<h3>Editing System Prompts</h3>
|
|
<p>To view or edit system prompts:</p>
|
|
<ol>
|
|
<li>Press <kbd>⌘,</kbd> to open Settings</li>
|
|
<li>Go to the <strong>Advanced</strong> tab</li>
|
|
<li>Scroll to the <strong>System Prompts</strong> section</li>
|
|
<li>View the default prompt (read-only)</li>
|
|
<li>Add your custom instructions in the editable field below</li>
|
|
</ol>
|
|
|
|
<h3>Best Practices</h3>
|
|
<ul>
|
|
<li><strong>Be Specific</strong> - Clear instructions produce better results</li>
|
|
<li><strong>Keep It Simple</strong> - Don't overcomplicate your custom prompt</li>
|
|
<li><strong>Test Changes</strong> - Try your prompt with a few messages to see if it works</li>
|
|
<li><strong>Start Empty</strong> - The default prompt works well; only add custom instructions if needed</li>
|
|
<li><strong>Avoid Contradictions</strong> - Don't contradict the default prompt's guidelines</li>
|
|
</ul>
|
|
|
|
<div class="warning">
|
|
<strong>⚠️ Important:</strong> Custom prompts affect all conversations. Changes apply immediately to new messages. If you experience unexpected behavior, try removing your custom prompt.
|
|
</div>
|
|
</section>
|
|
</main>
|
|
|
|
<footer>
|
|
<p>© 2026 oAI - Rune Olsen. For support or feedback, visit <a href="https://gitlab.pm/rune/oai-swift">gitlab.pm</a> or <a href="mailto:support@fubar.pm?subject=oAI Support&body=What can I help you with?">Contact Us</a>.</p>
|
|
</footer>
|
|
</div>
|
|
</body>
|
|
</html>
|