1713 lines
94 KiB
HTML
1713 lines
94 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="#anytype">Anytype Integration</a></li>
|
|
<li><a href="#bash-execution">Bash Execution</a></li>
|
|
<li><a href="#icloud-backup">iCloud Backup</a></li>
|
|
<li><a href="#reasoning">Reasoning / Thinking Tokens</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. The app is available in English, Norwegian Bokmål, Swedish, Danish, and German — it follows your macOS language preference automatically.</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>Searching & Filtering</h3>
|
|
<p>Type in the search bar to filter by model name, ID, or description. Quick-filter buttons narrow results by capability:</p>
|
|
<ul>
|
|
<li><strong>👁️ Vision</strong> — models that can read images</li>
|
|
<li><strong>🔧 Tools</strong> — models that can call tools (MCP, web search, bash)</li>
|
|
<li><strong>🌐 Online</strong> — models with built-in web search</li>
|
|
<li><strong>🎨 Image Gen</strong> — models that generate images</li>
|
|
<li><strong>🧠 Thinking</strong> — models that support reasoning / thinking tokens</li>
|
|
</ul>
|
|
|
|
<h3>Sorting</h3>
|
|
<p>Click the <strong>↑↓ Sort</strong> button to sort the list by:</p>
|
|
<ul>
|
|
<li><strong>Default</strong> — provider order, with favourites floated to the top</li>
|
|
<li><strong>Price: Low to High</strong> — cheapest per million tokens first</li>
|
|
<li><strong>Price: High to Low</strong> — most capable/expensive first</li>
|
|
<li><strong>Context: High to Low</strong> — largest context window first</li>
|
|
</ul>
|
|
|
|
<h3>Favourite Models</h3>
|
|
<p>Click the <strong>★</strong> star next to any model name to mark it as a favourite. Favourites:</p>
|
|
<ul>
|
|
<li>Float to the top of the Default sort order</li>
|
|
<li>Can be filtered to show only with the <strong>☆</strong> star button in the toolbar</li>
|
|
<li>Are shown as a filled yellow star ★ in the model row, the Model Info sheet, and the header bar</li>
|
|
<li>Are shared across all three places — toggling in any one updates all</li>
|
|
</ul>
|
|
|
|
<h3>Model Information</h3>
|
|
<p>Click the <strong>ⓘ</strong> icon on any model row to open a full details sheet — context length, pricing, capabilities, and description — without selecting that model. The sheet also has a ★ star button to toggle favourites. You can also type:</p>
|
|
<code class="command">/info</code>
|
|
<p class="note">Shows information about the currently selected model.</p>
|
|
|
|
<h3>Keyboard Navigation</h3>
|
|
<p>Use <kbd>↑</kbd> / <kbd>↓</kbd> to move through the list, <kbd>Return</kbd> to select the highlighted model.</p>
|
|
|
|
<h3>Default Model</h3>
|
|
<p>Set a model that oAI always opens with in <strong>Settings → General → Model Settings → Default Model</strong>. Click <strong>Choose…</strong> to pick from the full model list, or <strong>Clear</strong> to remove the default. Switching models during a chat session does <em>not</em> change your saved default — it only changes the current session.</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>
|
|
|
|
<h3>Tool Call Inspection</h3>
|
|
<p>When the AI uses tools (file access, web search, bash commands), a <strong>🔧 Calling: …</strong> system message appears in the chat. Click it to expand an inline view showing each tool's input arguments and result as pretty-printed JSON. A spinner indicates a pending tool call; a green checkmark shows when it completes.</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>, click <strong>+ Add Folder…</strong> in Settings → MCP, or drag a folder from Finder onto the allowed folders list</li>
|
|
<li>Ask the AI questions about your files</li>
|
|
</ol>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Drag & Drop:</strong> You can drag one or more folders directly from Finder onto the allowed folders area in Settings → MCP. The list highlights when you drag over it, and multiple folders can be dropped at once.
|
|
</div>
|
|
|
|
<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>
|
|
|
|
<p>From the <strong>File menu</strong> you also have:</p>
|
|
<ul>
|
|
<li><strong>Save Chat (<kbd>⌘S</kbd>)</strong> — Re-saves under the current name, or prompts for a name if the conversation hasn't been saved yet.</li>
|
|
<li><strong>Save Chat As…</strong> — Always prompts for a new name and creates a fresh copy, switching the session to that copy. Useful for branching a conversation.</li>
|
|
</ul>
|
|
|
|
<h3>Renaming Conversations</h3>
|
|
<p>In the Conversations list (<kbd>⌘L</kbd>):</p>
|
|
<ul>
|
|
<li>Click the <strong>✏️ pencil icon</strong> next to any conversation to rename it inline.</li>
|
|
<li>Swipe left on a conversation row to reveal <strong>Rename</strong>, <strong>Export</strong>, and <strong>Delete</strong> actions.</li>
|
|
</ul>
|
|
<p class="note">If the renamed conversation is currently open, the session name updates immediately so <kbd>⌘S</kbd> saves under the new 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>
|
|
|
|
<!-- Bash Execution -->
|
|
<section id="bash-execution">
|
|
<h2>Bash Execution</h2>
|
|
<p>When enabled, the AI can run shell commands directly on your Mac via <code>/bin/zsh</code>. This lets it read output, run scripts, compile code, check system state, and more — all without leaving the chat.</p>
|
|
|
|
<div class="warning">
|
|
<strong>⚠️ Security:</strong> Bash execution gives the AI the ability to run arbitrary commands on your machine. Only enable it when you need it, and use the approval prompt to review each command before it runs.
|
|
</div>
|
|
|
|
<h3>Enabling Bash Execution</h3>
|
|
<ol>
|
|
<li>Press <kbd>⌘,</kbd> to open Settings</li>
|
|
<li>Go to the <strong>MCP</strong> tab</li>
|
|
<li>Scroll to the <strong>Bash Execution</strong> section</li>
|
|
<li>Toggle <strong>Enable Bash Execution</strong> on</li>
|
|
</ol>
|
|
|
|
<div class="note">
|
|
<strong>Note:</strong> Bash execution is disabled by default and must be explicitly turned on. It is independent of MCP — you do not need MCP folders configured to use it.
|
|
</div>
|
|
|
|
<h3>Approval Prompt</h3>
|
|
<p>When <strong>Require Approval</strong> is enabled (the default), a sheet appears before each command showing:</p>
|
|
<ul>
|
|
<li>The full command to be run</li>
|
|
<li>The working directory</li>
|
|
<li>A security warning</li>
|
|
</ul>
|
|
<p>You can then choose:</p>
|
|
<ul>
|
|
<li><strong>Allow Once</strong> — run this command and ask again next time</li>
|
|
<li><strong>Allow for Session</strong> — skip the approval prompt for the rest of this chat</li>
|
|
<li><strong>Deny</strong> — cancel the command; the AI is told it was rejected</li>
|
|
</ul>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Session Scope:</strong> "Allow for Session" resets when you start a new chat, switch models, or load a saved conversation. It is never permanent.
|
|
</div>
|
|
|
|
<h3>Configuration Options</h3>
|
|
<dl class="commands">
|
|
<dt>Working Directory</dt>
|
|
<dd>The directory commands run in (default: <code>~</code>). Set to your project folder to avoid needing full paths.</dd>
|
|
|
|
<dt>Timeout</dt>
|
|
<dd>Maximum seconds a command can run before being killed (default: 30 s). Increase for long-running builds.</dd>
|
|
|
|
<dt>Require Approval</dt>
|
|
<dd>Show the approval sheet before each command (default: on). Disable only if you fully trust the AI's judgment for the current session.</dd>
|
|
</dl>
|
|
|
|
<h3>Output Limits</h3>
|
|
<p>To keep the context manageable, output is capped:</p>
|
|
<ul>
|
|
<li><strong>stdout</strong>: first 20,000 characters</li>
|
|
<li><strong>stderr</strong>: first 5,000 characters</li>
|
|
</ul>
|
|
<p>If output is truncated, the AI sees a note indicating how much was omitted.</p>
|
|
|
|
<h3>Example Usage</h3>
|
|
<div class="example">
|
|
<p><strong>You:</strong> "Run the test suite and tell me what's failing."</p>
|
|
<p><strong>AI:</strong> <em>(bash approval sheet appears with <code>cd ~/myproject && swift test</code>)</em></p>
|
|
<p><strong>After Allow:</strong> "3 tests failed: testLogin, testSignup, testLogout. The error in testLogin is…"</p>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- iCloud Backup -->
|
|
<section id="icloud-backup">
|
|
<h2>iCloud Backup</h2>
|
|
<p>Back up and restore all your oAI settings with one click. Backups are saved to iCloud Drive so they're available on any Mac where you're signed in.</p>
|
|
|
|
<div class="note">
|
|
<strong>What is included:</strong> All settings and preferences — providers, model defaults, MCP configuration, appearance, advanced options, shortcuts, skills, and more.<br><br>
|
|
<strong>What is excluded:</strong> API keys, passwords, and other credentials. These are intentionally left out for security and must be re-entered after restoring on a new machine.
|
|
</div>
|
|
|
|
<h3>Backing Up</h3>
|
|
<ol>
|
|
<li>Press <kbd>⌘,</kbd> to open Settings</li>
|
|
<li>Go to the <strong>Backup</strong> tab</li>
|
|
<li>Click <strong>Back Up Now</strong></li>
|
|
</ol>
|
|
<p>The backup file is saved to <code>~/iCloud Drive/oAI/oai_backup.json</code>. If iCloud Drive is not available, it falls back to your Downloads folder. The date of the last backup is shown in the tab.</p>
|
|
|
|
<h3>Restoring</h3>
|
|
<ol>
|
|
<li>Open Settings → <strong>Backup</strong> tab</li>
|
|
<li>Click <strong>Restore from File…</strong></li>
|
|
<li>Select your <code>oai_backup.json</code> file</li>
|
|
<li>Settings are applied immediately — no restart required</li>
|
|
<li>Re-enter your API keys in Settings → <strong>General</strong></li>
|
|
</ol>
|
|
|
|
<div class="tip">
|
|
<strong>💡 New Mac Setup:</strong> Back up on your old Mac, sign in to iCloud on your new Mac, open oAI, restore from the backup file — and all your settings are restored in seconds. You only need to re-enter API keys.
|
|
</div>
|
|
|
|
<h3>Backup Format</h3>
|
|
<p>Backups are plain JSON files (versioned for forward compatibility). You can inspect them in any text editor. The format is designed to be safe to share — no credentials are ever included.</p>
|
|
</section>
|
|
|
|
<!-- Reasoning / Thinking Tokens -->
|
|
<section id="reasoning">
|
|
<h2>Reasoning / Thinking Tokens</h2>
|
|
<p>Some AI models can "think out loud" before giving their final answer — reasoning through the problem step by step. oAI streams this thinking content live and displays it in a collapsible block above the response.</p>
|
|
|
|
<h3>Supported Models</h3>
|
|
<p>Reasoning is available on models that support extended thinking, including:</p>
|
|
<ul>
|
|
<li>DeepSeek R1 and DeepSeek R1 variants (via OpenRouter)</li>
|
|
<li>Qwen thinking models (via OpenRouter)</li>
|
|
<li>Claude 3.7+ with extended thinking (via Anthropic or OpenRouter)</li>
|
|
<li>OpenAI o1, o3, and similar reasoning models</li>
|
|
<li>Grok reasoning models (via OpenRouter)</li>
|
|
</ul>
|
|
<p>Look for the <strong>🧠</strong> badge in the model selector to identify thinking-capable models. Use the <strong>🧠 Thinking</strong> quick-filter to show only reasoning models.</p>
|
|
|
|
<h3>Enabling Reasoning</h3>
|
|
<ol>
|
|
<li>Press <kbd>⌘,</kbd> to open Settings</li>
|
|
<li>Go to the <strong>General</strong> tab → <strong>Features</strong> section</li>
|
|
<li>Toggle <strong>Reasoning</strong> on</li>
|
|
</ol>
|
|
<p class="note">Reasoning only activates when the selected model supports extended thinking (🧠 badge). The setting has no effect on standard models.</p>
|
|
|
|
<h3>Effort Level</h3>
|
|
<p>The effort level controls how many tokens the model spends on reasoning (as a share of its total token budget):</p>
|
|
<dl class="commands">
|
|
<dt>High (~80%)</dt>
|
|
<dd>Deep, methodical reasoning. Best for math, logic, multi-step planning, and complex coding tasks. More expensive.</dd>
|
|
|
|
<dt>Medium (~50%)</dt>
|
|
<dd>Balanced reasoning. Good for most tasks that benefit from thinking (default).</dd>
|
|
|
|
<dt>Low (~20%)</dt>
|
|
<dd>Light reasoning pass. Suitable for moderately complex questions without a large token budget.</dd>
|
|
|
|
<dt>Minimal (~10%)</dt>
|
|
<dd>Minimal internal thinking — just a quick check before answering. Fastest and cheapest.</dd>
|
|
</dl>
|
|
|
|
<h3>Hiding Reasoning Content</h3>
|
|
<p>Enable <strong>Hide reasoning content</strong> in Settings → General → Features to keep reasoning internal. The model still thinks at the selected effort level, but the thinking block is not shown — only the final answer appears in chat.</p>
|
|
|
|
<h3>In-Chat Experience</h3>
|
|
<p>When reasoning is enabled and a thinking-capable model responds:</p>
|
|
<ol>
|
|
<li>A <strong>🧠 Thinking…</strong> block appears above the response and auto-expands</li>
|
|
<li>Reasoning content streams in live as the model thinks</li>
|
|
<li>When the final answer starts arriving, the thinking block collapses automatically</li>
|
|
<li>Click the block header at any time to manually expand or collapse it</li>
|
|
</ol>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Tip:</strong> Medium effort is a great default. Switch to High for math problems, deep code analysis, or anything requiring careful step-by-step reasoning.
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Keyboard Shortcuts -->
|
|
<!-- Anytype Integration -->
|
|
<section id="anytype">
|
|
<h2>Anytype Integration</h2>
|
|
<p>oAI can connect to your local <a href="https://anytype.io" target="_blank">Anytype</a> desktop app, giving the AI read and write access to your personal knowledge base. All data stays on your machine — the API is local-only.</p>
|
|
|
|
<h3>Requirements</h3>
|
|
<ul>
|
|
<li>Anytype desktop app installed and running</li>
|
|
<li>An API key generated inside Anytype (Settings → Integrations)</li>
|
|
</ul>
|
|
|
|
<h3>Setup</h3>
|
|
<ol>
|
|
<li>Open oAI Settings → Anytype tab</li>
|
|
<li>Enable the toggle</li>
|
|
<li>Enter your API key (leave the URL as the default unless your setup is unusual)</li>
|
|
<li>Click <strong>Test Connection</strong> — a success message will show how many spaces were found</li>
|
|
</ol>
|
|
|
|
<h3>What the AI Can Do</h3>
|
|
<ul>
|
|
<li><strong>Search</strong> — find objects by keyword across all spaces or within a specific one</li>
|
|
<li><strong>Read</strong> — open any object and read its full markdown content</li>
|
|
<li><strong>Create</strong> — make new notes, tasks, or pages</li>
|
|
<li><strong>Append</strong> — add content to the end of an existing object without touching the rest (recommended for edits)</li>
|
|
<li><strong>Update</strong> — rewrite the full body of an object (use only when truly restructuring content)</li>
|
|
<li><strong>Checkboxes</strong> — toggle individual to-do checkboxes by text match, or mark tasks done via their native relation</li>
|
|
</ul>
|
|
|
|
<div class="tip">
|
|
<strong>💡 Tip — Append vs Update:</strong> Use <em>append</em> whenever you want to add content to an existing note. It fetches the current body, adds your new content at the end, and saves — leaving all existing text, links, and internal Anytype references intact. <em>Update</em> replaces the entire body and can degrade rich Anytype internal links (anytype://...) to plain text.
|
|
</div>
|
|
|
|
<h3>Example Prompts</h3>
|
|
<ul>
|
|
<li>"Search my Anytype for notes about Swift concurrency"</li>
|
|
<li>"Create a new task called 'Review PR #42' in my Work space"</li>
|
|
<li>"Add today's meeting summary to my Weekly Notes object"</li>
|
|
<li>"Mark the 'Buy groceries' checkbox as done in my Shopping List"</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<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>Save Chat (re-saves if already named, prompts for name otherwise)</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>General Tab</h3>
|
|
<ul>
|
|
<li>Add and manage API keys for all providers (OpenAI, Anthropic, OpenRouter, Google, Ollama)</li>
|
|
<li>Switch between providers and set the default model</li>
|
|
<li>Configure streaming, memory, online mode, and max tokens</li>
|
|
<li><strong>Features</strong>:
|
|
<ul>
|
|
<li><strong>Reasoning</strong> — enable thinking tokens, set effort level (High / Medium / Low / Minimal), optionally hide reasoning content from chat (see <a href="#reasoning">Reasoning / Thinking Tokens</a>)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>MCP Tab</h3>
|
|
<ul>
|
|
<li>Enable/disable MCP file access</li>
|
|
<li>Add folders via the <strong>+ Add Folder…</strong> button, or drag from Finder</li>
|
|
<li>Enable/disable write, delete, move, and bash execution permissions</li>
|
|
<li>Configure gitignore respect</li>
|
|
<li><strong>Bash Execution</strong> — enable AI shell access, set working directory, timeout, and approval behaviour (see <a href="#bash-execution">Bash Execution</a>)</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>Paperless Tab <span style="font-size: 0.75em; background: #f90; color: #fff; border-radius: 4px; padding: 1px 5px; vertical-align: middle;">Beta</span></h3>
|
|
<p>Connect oAI to a self-hosted <a href="https://docs.paperless-ngx.com" target="_blank">Paperless-NGX</a> instance so the AI can search and read your document archive.</p>
|
|
<ul>
|
|
<li><strong>URL</strong> — Base URL of your Paperless instance (e.g. <code>https://paperless.yourdomain.com</code>)</li>
|
|
<li><strong>API Token</strong> — Found in Paperless → Settings → API Tokens</li>
|
|
<li><strong>Test Connection</strong> — Verify connectivity and display document count</li>
|
|
</ul>
|
|
<p>When enabled, the AI can use <code>paperless_search</code>, <code>paperless_get_document</code>, <code>paperless_list_tags</code>, and other tools to interact with your document library.</p>
|
|
<p class="note"><strong>Beta:</strong> Paperless integration is under active development. Some features may be incomplete or behave unexpectedly.</p>
|
|
|
|
<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>
|
|
|
|
<h3>Backup Tab</h3>
|
|
<p>One-click backup and restore of all settings to iCloud Drive. See <a href="#icloud-backup">iCloud Backup</a> for full details.</p>
|
|
<ul>
|
|
<li><strong>Back Up Now</strong> — exports settings to <code>~/iCloud Drive/oAI/oai_backup.json</code></li>
|
|
<li><strong>Restore from File…</strong> — imports settings from a backup file</li>
|
|
<li>API keys and credentials are excluded from backups and must be re-entered after restore</li>
|
|
</ul>
|
|
|
|
<h3>Anytype Tab</h3>
|
|
<p>Connect oAI to your local <a href="https://anytype.io" target="_blank">Anytype</a> desktop app so the AI can search, read, and add content to your knowledge base.</p>
|
|
<ul>
|
|
<li><strong>Enable Anytype</strong> — toggle to activate the integration</li>
|
|
<li><strong>API URL</strong> — local Anytype API endpoint (default: <code>http://127.0.0.1:31009</code>)</li>
|
|
<li><strong>API Key</strong> — generated in Anytype → Settings → Integrations</li>
|
|
<li><strong>Test Connection</strong> — verify connectivity and list available spaces</li>
|
|
</ul>
|
|
<p>When enabled, the AI has access to these tools:</p>
|
|
<ul>
|
|
<li><code>anytype_search_global</code> / <code>anytype_search_space</code> — search across all or a specific space</li>
|
|
<li><code>anytype_list_spaces</code> / <code>anytype_get_space_objects</code> — explore your spaces</li>
|
|
<li><code>anytype_get_object</code> — read the full markdown body of any object</li>
|
|
<li><code>anytype_create_object</code> — create a new note, task, or page</li>
|
|
<li><code>anytype_append_to_object</code> — <strong>add content to an existing object without rewriting it</strong> (preferred for edits — preserves Anytype internal links)</li>
|
|
<li><code>anytype_update_object</code> — replace the full body (use sparingly; prefer append)</li>
|
|
<li><code>anytype_toggle_checkbox</code> — surgically check/uncheck a to-do item by text match</li>
|
|
<li><code>anytype_set_done</code> — mark a task done/undone via its native relation</li>
|
|
</ul>
|
|
<p class="note"><strong>Note:</strong> The Anytype desktop app must be running for the integration to work. The API is local-only — no data leaves your machine.</p>
|
|
</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>
|