New version v2.3.6
This commit is contained in:
@@ -35,6 +35,9 @@
|
||||
<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="#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>
|
||||
@@ -45,7 +48,7 @@
|
||||
<!-- 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>
|
||||
<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>
|
||||
@@ -101,10 +104,32 @@
|
||||
<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</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>Model Information</h3>
|
||||
<p>View details about any model:</p>
|
||||
<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. You can also type:</p>
|
||||
<code class="command">/info</code>
|
||||
<p class="note">Shows information about the currently selected model including context length, pricing, and capabilities.</p>
|
||||
<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>Your selected model is automatically saved and will be restored when you restart the app.</p>
|
||||
@@ -133,6 +158,9 @@
|
||||
<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 -->
|
||||
@@ -408,10 +436,14 @@
|
||||
<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>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>
|
||||
@@ -456,6 +488,20 @@
|
||||
<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>
|
||||
@@ -1155,6 +1201,165 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
|
||||
</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 -->
|
||||
<section id="keyboard-shortcuts">
|
||||
<h2>Keyboard Shortcuts</h2>
|
||||
@@ -1183,6 +1388,9 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
|
||||
<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>
|
||||
@@ -1211,18 +1419,25 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
|
||||
<h2>Settings</h2>
|
||||
<p>Customize oAI to your preferences. Press <kbd>⌘,</kbd> to open Settings.</p>
|
||||
|
||||
<h3>Providers Tab</h3>
|
||||
<h3>General Tab</h3>
|
||||
<ul>
|
||||
<li>Add and manage API keys for different providers</li>
|
||||
<li>Switch between providers</li>
|
||||
<li>Set default models</li>
|
||||
<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>Manage folder access permissions</li>
|
||||
<li>Enable/disable write operations</li>
|
||||
<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>
|
||||
@@ -1294,6 +1509,16 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
|
||||
<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>
|
||||
|
||||
@@ -1312,9 +1537,17 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
|
||||
<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>
|
||||
<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>
|
||||
</section>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user