oAI Help

Getting Started

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.

AI Providers & API Keys

oAI supports multiple AI providers. You'll need an API key from at least one provider to use the app.

Supported Providers

• OpenRouter - Access to 300+ models through a single API (openrouter.ai)
• Anthropic - Claude models (Opus, Sonnet, Haiku) (console.anthropic.com)
• OpenAI - GPT-4, GPT-4 Turbo, GPT-3.5 models (platform.openai.com)
• Ollama - Run models locally on your Mac (ollama.ai)

Adding an API Key

1. Press ⌘, or type /config to open Settings
2. Select the Providers tab
3. Enter your API key for the desired provider
4. Click Save

Switching Providers

Use the provider dropdown in the header or type:

Selecting Models

Different models have different capabilities, speeds, and costs. Choose the right model for your task.

Opening the Model Selector

• Press ⌘M
• Type /model
• Click the model name in the header

Searching & Filtering

Type in the search bar to filter by model name, ID, or description. Quick-filter buttons narrow results by capability:

• 👁️ Vision — models that can read images
• 🔧 Tools — models that can call tools (MCP, web search, bash)
• 🌐 Online — models with built-in web search
• 🎨 Image Gen — models that generate images
• 🧠 Thinking — models that support reasoning / thinking tokens

Sorting

Click the ↑↓ Sort button to sort the list by:

• Default — provider order, with favourites floated to the top
• Price: Low to High — cheapest per million tokens first
• Price: High to Low — most capable/expensive first
• Context: High to Low — largest context window first

Favourite Models

Click the ★ star next to any model name to mark it as a favourite. Favourites:

• Float to the top of the Default sort order
• Can be filtered to show only with the ☆ star button in the toolbar
• Are shown as a filled yellow star ★ in the model row, the Model Info sheet, and the header bar
• Are shared across all three places — toggling in any one updates all

Model Information

Click the ⓘ 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:

Shows information about the currently selected model.

Keyboard Navigation

Use ↑ / ↓ to move through the list, Return to select the highlighted model.

Default Model

Set a model that oAI always opens with in Settings → General → Model Settings → Default Model. Click Choose… to pick from the full model list, or Clear to remove the default. Switching models during a chat session does not change your saved default — it only changes the current session.

Sending Messages

Basic Usage

• Type your message in the input field
• Press Return to send (single-line messages)
• Press ⇧Return to add a new line without sending

During Generation

While the AI is responding:

• Press Esc to cancel generation
• Click the Stop button (red circle)
• Cancelled responses show a ⚠️ interrupted indicator

Retrying Messages

If you're not satisfied with a response:

Resends your last message to generate a new response.

Tool Call Inspection

When the AI uses tools (file access, web search, bash commands), a 🔧 Calling: … 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.

File Attachments

Attach files to your messages for the AI to analyze. Supports images, PDFs, and text files.

Attaching Files

• Click the 📎 paperclip icon to browse and select files
• Type @/path/to/file.txt in your message
• Type @~/Documents/image.png for files in your home directory

Supported File Types

• Images: PNG, JPEG, GIF, WebP, BMP, SVG (max 10 MB)
• Documents: PDF (max 10 MB)
• Text: TXT, code files, logs, etc. (max 50 KB)

Slash Commands

Commands start with / and provide quick access to features. Type / to see suggestions.

Chat Commands

/history

View command history with timestamps (European format: dd.MM.yyyy). Search by text or date to find previous messages

/clear

Clear all messages from the current session

/retry

Retry your last message to get a new response

/memory on|off

Toggle conversation memory. When off, only your latest message is sent (no conversation history)

/online on|off

Enable/disable web search. When on, the AI can search the web for current information

Model & Provider Commands

/model

Open the model selector

/provider [name]

Switch AI provider or show current provider

/info

Display information about the current model

/credits

Check your account balance (OpenRouter only)

Conversation Commands

/save <name>

Save the current conversation

/load

Browse and load a saved conversation

/list

Show all saved conversations

/delete <name>

Delete a saved conversation

/export md|json

Export conversation as Markdown or JSON

MCP Commands

/mcp on|off

Enable/disable file access for the AI

/mcp add <path>

Grant AI access to a folder

/mcp remove <path>

Revoke AI access to a folder

/mcp list

Show all accessible folders

/mcp status

Display MCP status and permissions

/mcp write on|off

Enable/disable write permissions

Shortcuts & Skills Commands

/shortcuts

Open the Shortcuts manager to create, edit, and manage your custom prompt template commands

/skills

Open the Agent Skills manager to install and manage SKILL.md-style behavioral instruction files

/<your-command>

Run any shortcut you've created. Example: /summarize to run your "Summarize" shortcut

Settings Commands

/config, /settings

Open the settings panel

/stats

Show session statistics (messages, tokens, cost)

Memory & Context

oAI features an enhanced memory and context system with intelligent message selection, semantic search, and automatic summarization.

Basic Memory Control

Control whether the AI remembers previous messages:

Smart Context Selection

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.

How It Works

• Always includes the last 10 messages (recent context)
• Includes starred messages (user-marked as important)
• Includes high-importance messages (high cost, detailed content)
• Respects model context limits

Enabling Smart Context

1. Go to Settings → Advanced
2. Enable "Smart Context Selection"
3. Set max context tokens (default: 100,000)

Message Starring

Star important messages to always include them in context, regardless of age:

1. Hover over any user or assistant message
2. Click the star icon (⭐) in the header
3. Starred messages show a filled yellow star

Semantic Search

Find conversations by meaning, not just keywords. Powered by AI embeddings.

Setup

1. Go to Settings → Advanced → Semantic Search
2. Enable "Enable Embeddings"
3. Requires API key for OpenAI, OpenRouter, or Google
4. Choose your preferred embedding provider and model
5. Click "Embed All Conversations" (one-time, ~$0.04 for 10k messages)

Using Semantic Search

1. Open conversation list (/list or ⌘L)
2. Type your search query
3. Toggle "Semantic" switch ON
4. Results ranked by meaning, not keyword matching

Progressive Summarization

For very long conversations, oAI automatically summarizes older messages to save tokens while preserving context.

How It Works

• When conversation exceeds threshold (default: 50 messages)
• Older messages (0-30) are summarized into 2-3 paragraphs
• Summary focuses on key topics, decisions, and information
• Recent messages (last 20) always sent in full
• Summaries included in system prompt for context

Enabling Summarization

1. Go to Settings → Advanced → Progressive Summarization
2. Enable "Enable Summarization"
3. Set message threshold (default: 50)

All Three Together

When all features are enabled:

1. Smart Context Selection: Picks relevant messages (15-20 from 100)
2. Progressive Summarization: Provides summaries of excluded old messages
3. Semantic Search: Find conversations by meaning

Online Mode (Web Search)

Enable the AI to search the web for current information before responding.

When to Use Online Mode

• Questions about current events
• Recent news or updates
• Real-time data (weather, stocks, etc.)
• Information beyond the AI's training cutoff

Enabling Online Mode

How It Works

When online mode is enabled:

1. Your question is used to search the web
2. Relevant results are retrieved
3. Search results are added to your message context
4. The AI uses the web results to inform its response

MCP (File Access)

MCP (Model Context Protocol) allows the AI to access, read, and optionally modify files on your computer.

Setting Up MCP

1. Enable MCP: /mcp on
2. Add a folder: /mcp add ~/Projects/myapp, click + Add Folder… in Settings → MCP, or drag a folder from Finder onto the allowed folders list
3. Ask the AI questions about your files

What the AI Can Do

Read permissions (always enabled when MCP is on):

• Read file contents
• List directory contents
• Search for files
• Get file information (size, modified date, etc.)

Write permissions (optional, disabled by default):

• Write and edit files
• Create new files
• Delete files
• Create directories
• Move and copy files

Managing Permissions

Toggle all write permissions:

For fine-grained control, open Settings → MCP to enable/disable individual permissions.

Gitignore Respect

When enabled in Settings, MCP will ignore files and folders listed in .gitignore files.

Example Usage

Managing Conversations

Save, load, search, and export your chat conversations.

Saving Conversations

Saves all current messages under the specified name.

From the File menu you also have:

• Save Chat (⌘S) — Re-saves under the current name, or prompts for a name if the conversation hasn't been saved yet.
• Save Chat As… — Always prompts for a new name and creates a fresh copy, switching the session to that copy. Useful for branching a conversation.

Renaming Conversations

In the Conversations list (⌘L):

• Click the ✏️ pencil icon next to any conversation to rename it inline.
• Swipe left on a conversation row to reveal Rename, Export, and Delete actions.

If the renamed conversation is currently open, the session name updates immediately so ⌘S saves under the new name.

Loading Conversations

Opens a list of saved conversations. Select one to load.

Viewing Saved Conversations

• Press ⌘L
• Type /list

Searching Conversations

Two search modes available in the conversation list:

• Keyword Search (default): Matches conversation titles
• Semantic Search: Finds conversations by meaning (requires embeddings enabled)

Deleting Conversations

Warning: This action cannot be undone.

Bulk Delete

In the conversation list:

1. Click "Select" button
2. Click conversations to select (checkbox appears)
3. Click "Delete (N)" button

Exporting Conversations

Export to Markdown or JSON format:

Files are saved to your Downloads folder.

Git Sync (Backup & Sync)

Automatically backup and synchronize your conversations across multiple machines using Git.

Getting Started

1. Create a Git repository on your preferred service:
   • GitHub (free private repos)
   • GitLab (free private repos)
   • Gitea (self-hosted)
2. Open Settings (⌘,) → Sync tab
3. Enter your repository URL (e.g., https://github.com/username/oai-sync.git)
4. Choose authentication method:
   • SSH Key - Most secure, recommended
   • Username + Password - Simple but less secure
   • Access Token - Good balance of security and convenience
5. Click Clone Repository to initialize

Auto-Save Features

When auto-save is enabled, oAI automatically saves and syncs conversations based on triggers:

Auto-Save Triggers

• On App Start - Pulls and imports changes when oAI launches (no push)
• On Model Switch - Saves when you change AI models
• On App Quit - Saves before oAI closes
• After Idle Timeout - Saves after 5 seconds of inactivity

Auto-Save Settings

• Minimum Messages - Only save conversations with at least N messages (default: 5)
• Auto-Export - Export conversations to markdown after save
• Auto-Commit - Commit changes to git automatically
• Auto-Push - Push commits to remote repository

Manual Sync Operations

Use manual controls for fine-grained sync operations:

Clone Repository

Initialize a fresh clone of your remote repository

Export All

Export all conversations to markdown files (does not commit)

Push

Export conversations, commit changes, and push to remote

Pull

Fetch latest changes from remote repository

Import

Import all conversations from markdown files into the database

Sync Status Indicators

oAI shows sync status in two places:

Header Indicator (Green/Orange/Red Pill)

• 🟢 Synced - Last sync successful
• 🟠 Syncing... - Sync in progress
• 🔴 Error - Sync failed (check error message)

Footer Status (Bottom-Left)

• Last Sync: 2m ago - Shows time since last successful sync
• Not Synced - Repository cloned but no sync yet
• Error With Sync - Last sync attempt failed

Markdown Export Format

Conversations are exported as markdown files with metadata:

# Conversation Title

ID: uuid
Created: 2026-02-13T10:30:00.000Z
Updated: 2026-02-13T11:45:00.000Z
Primary Model: gpt-4
Models Used: gpt-4, claude-3-sonnet

---

## User
What's the weather like?

Model: gpt-4 | Tokens: 50 | Cost: $0.0001

---

## Assistant
The weather is sunny today!

Model: gpt-4 | Tokens: 120 | Cost: $0.0024

---

Model Tracking

Git Sync tracks which AI model generated each message:

• Primary Model - The main model used in the conversation
• Models Used - All models that contributed to the conversation
• Per-Message Model ID - Each message knows which model created it

Note: When you import conversations on a new machine, each message retains its original model information. This ensures perfect fidelity when syncing across devices.

Repository Structure

Your sync repository is organized as follows:

~/Library/Application Support/oAI/sync/
├── README.md                    # Warning about manual edits
└── conversations/
    ├── my-first-chat.md
    ├── python-help.md
    └── project-discussion.md

Restoring on a New Machine

To restore your conversations on a new Mac:

1. Install oAI on the new machine
2. Open Settings → Sync tab
3. Enter your repository URL and credentials
4. Click Clone Repository
5. Click Import to restore all conversations
6. Your conversations appear in the Conversations list with original model info intact

Authentication Methods

SSH Key (Recommended)

Most secure option. Generate an SSH key and add it to your Git service:

1. Generate key: ssh-keygen -t ed25519 -C "oai@yourmac"
2. Add to git service (GitHub Settings → SSH Keys)
3. Use SSH URL in oAI: git@github.com:username/repo.git

Access Token

Good balance of security and convenience:

• GitHub: Settings → Developer Settings → Personal Access Tokens → Generate new token
• GitLab: Settings → Access Tokens → Add new token
• Permissions needed: repo (full repository access)

Username + Password

Simple but less secure. Some services require app-specific passwords instead of your main password.

Best Practices

• Use Private Repositories - Your conversations may contain sensitive information
• Enable Auto-Sync on One Machine - Avoid conflicts by syncing automatically on your primary Mac only
• Manual Sync on Others - Use Pull/Push buttons on secondary machines
• Regular Backups - Git history preserves all versions of your conversations
• Don't Edit Manually - The README warns against manual edits; always use oAI's sync features

Troubleshooting

Sync Failed (Red Indicator)

• Check your internet connection
• Verify authentication credentials
• Ensure repository URL is correct
• Check footer for detailed error message

Merge Conflicts

• Stop auto-sync on all but one machine
• Manually resolve conflicts in the git repository
• Commit and push the resolution
• Pull on other machines

Import Shows "0 imported, N skipped"

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).

Email Handler (AI Assistant)

Turn oAI into an AI-powered email auto-responder. Monitor an inbox and automatically reply to emails with intelligent, context-aware responses.

How It Works

1. IMAP Monitoring - oAI polls your inbox every 30 seconds for new emails
2. Subject Filter - Only emails with your identifier (e.g., [Jarvis]) are processed
3. AI Processing - Email content is sent to your configured AI model
4. Auto-Reply - AI-generated response is sent via SMTP
5. Mark as Read - Processed emails are marked to prevent duplicates

Setting Up Email Handler

1. Press ⌘, to open Settings
2. Go to the Email tab
3. Enable Email Handler toggle
4. Configure server settings:
   • IMAP Host: Your incoming mail server (e.g., imap.gmail.com)
   • SMTP Host: Your outgoing mail server (e.g., smtp.gmail.com)
   • Username: Your email address
   • Password: Your email password or app-specific password
   • Ports: IMAP 993 (TLS), SMTP 465 (recommended) or 587
5. Click Test Connection to verify settings
6. Set Subject Identifier (e.g., [Jarvis])
7. Select AI Provider and Model for responses
8. Save settings and restart oAI

Email Server Settings

Gmail Setup

1. Enable IMAP: Gmail Settings → Forwarding and POP/IMAP → Enable IMAP
2. Create App Password: Google Account → Security → 2-Step Verification → App passwords
3. Use settings:
   • IMAP: imap.gmail.com port 993
   • SMTP: smtp.gmail.com port 465
   • Password: Use the generated app password, not your main password

Common IMAP/SMTP Settings

Gmail

IMAP: imap.gmail.com:993, SMTP: smtp.gmail.com:465

Outlook/Hotmail

IMAP: outlook.office365.com:993, SMTP: smtp.office365.com:587

iCloud

IMAP: imap.mail.me.com:993, SMTP: smtp.mail.me.com:587

Self-Hosted (Mailcow)

IMAP: mail.yourdomain.com:993, SMTP: mail.yourdomain.com:465

AI Configuration

Configure how the AI generates email responses:

• Provider: Choose which AI provider to use (Anthropic, OpenRouter, etc.)
• Model: Select the AI model (Claude Haiku for fast responses, Sonnet for quality)
• Max Tokens: Limit response length (default: 2000)
• Online Mode: Enable if AI should search web for current information
• System Prompt: Customize AI's personality and response style (optional)

Email Trigger (Subject Identifier)

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.

Examples

• [Jarvis] - Matches "Question [Jarvis]" or "[Jarvis] Help needed"
• [BOT] - Matches "[BOT] Customer inquiry"
• @AI - Matches "Support request @AI"

Rate Limiting

Prevent the AI from processing too many emails:

• Enable Rate Limit: Toggle to limit emails processed per hour
• Emails Per Hour: Maximum number of emails to process (default: 10)
• When limit is reached, additional emails are logged as errors

Email Log

Track all processed emails in the Email Log (Settings → Email → View Email Log):

• Success: Emails processed and replied to successfully
• Error: Failed processing with error details
• Timestamp: When the email was processed
• Sender: Who sent the email
• Subject: Email subject line

How Responses Are Generated

When an email is detected:

1. Email content is extracted (sender, subject, body)
2. Subject identifier is removed from the subject line
3. Content is sent to AI with system prompt: "You are an AI email assistant. Respond professionally..."
4. AI generates a plain text + HTML response
5. Reply is sent with proper email headers (In-Reply-To, References for threading)
6. Original email is marked as read

Response Time

Email handler uses IMAP polling (not real-time):

• Polling Interval: 30 seconds
• Average Latency: 15-30 seconds from email arrival to reply sent
• AI Processing: 2-15 seconds depending on model
• Total Response Time: ~20-45 seconds typically

Troubleshooting

Email Not Detected

• Verify subject identifier matches exactly (case-sensitive)
• Check email is in INBOX (not Spam/Junk)
• Ensure email handler is enabled in Settings
• Restart oAI to reinitialize monitoring
• Check logs: ~/Library/Logs/oAI.log

Connection Errors

• Verify IMAP/SMTP server addresses are correct
• Check ports: IMAP 993, SMTP 465 (or 587)
• Use app-specific password (Gmail, iCloud)
• Allow "less secure apps" if required by provider
• Check firewall isn't blocking connections

SMTP TLS Errors

• Use port 465 (direct TLS) instead of 587 (STARTTLS)
• Port 465 is more reliable with oAI's implementation
• If only 587 available, contact support

Authentication Failed

• Gmail: Use app password, not main password
• iCloud: Use app-specific password
• Outlook: Enable IMAP in account settings
• Double-check username is your full email address

Duplicate Replies

• Check Email Log for duplicate entries
• Emails should be marked as read after processing
• Restart oAI if duplicates persist

Best Practices

• Dedicated Email: Use a separate email account for AI automation
• Test First: Send test emails and verify responses before production use
• Monitor Email Log: Regularly check for errors or unexpected behavior
• Rate Limits: Enable rate limiting to prevent excessive API costs
• System Prompt: Customize the AI's response style with a custom system prompt
• Privacy: Don't use with emails containing sensitive information
• Backup: Keep copies of important emails; AI responses are automated

Example Workflow

From: customer@example.com
To: support@yourcompany.com
Subject: [Jarvis] Product question

Hi, what are your shipping options?

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

Shortcuts (Prompt Templates)

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.

Creating a Shortcut

1. Type /shortcuts or go to Settings → Shortcuts tab
2. Click New Shortcut
3. Set a command (e.g. /summarize)
4. Add a short description shown in the dropdown
5. Write your prompt template
6. Click Save

Using {{input}} Placeholder

If your template contains {{input}}, the AI waits for you to type something after the command. Your text replaces {{input}} before sending.

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?"

If your template has no {{input}}, the shortcut executes immediately when selected — no extra input needed.

Command: /hello
Template: Say hello in 5 different languages with a brief cultural note for each.

Usage: Type /hello → executes immediately

Shortcuts in the Command Dropdown

Your shortcuts appear in the / dropdown with a ⚡ prefix. Type the first letters of your command to filter them.

More Shortcut Examples

/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}}"

Import & Export

• Export All — saves all shortcuts as shortcuts.json in Downloads
• Import — load shortcuts from a JSON file (single shortcut or pack)
• When importing a duplicate command, you can choose: Replace, Keep Both, or Skip

Agent Skills (SKILL.md)

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.

Skills follow the SKILL.md open standard, making them compatible with a growing ecosystem of skill marketplaces and community collections.

Installing a Skill

1. Type /skills or go to Settings → Skills tab
2. Click Import to load a .md file or a .zip skill bundle, or
3. Click New Skill to write your own from scratch
4. Toggle the skill Active to inject it into the system prompt

SKILL.md Format

A skill is a plain Markdown file. The first # Heading becomes the skill name. Write instructions in natural language — the AI decides when to apply them.

# 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

# 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

Writing Your Own Skills

• Start with a # Title — this becomes the skill name in the list
• Use bullet points for rules and guidelines
• Be specific: "always check X" is better than "be careful with X"
• Keep skills focused on one area — create multiple skills rather than one huge one
• The AI reads all active skills before responding — shorter, clearer skills work better

How Skills Are Applied

Active skills are appended to the system prompt under an "Installed Skills" section. The AI sees them with every message and applies relevant guidance automatically. You can toggle skills on/off without deleting them.

Skill Support Files

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.

Adding Files to a Skill

1. Open the skill editor (click Edit on any skill)
2. Scroll to the Files section at the bottom
3. Click Add File and select one or more text files
4. Files appear in a list with name and size
5. Click the trash icon next to any file to remove it

How Files Are Injected

In the system prompt, each file is included as a labelled fenced code block immediately after the skill's instructions:

### Daily AI News

[skill instructions here]

**Skill Data Files:**

**news_sources.json:**
```json
{ "sources": [...] }
```

**search_queries.md:**
```md
...
```

File Storage

Files are stored locally at:

~/Library/Application Support/oAI/skills/<skill-uuid>/
├── news_sources.json
└── search_queries.md

Deleting a skill also deletes its file directory automatically.

Import & Export

Importing

Click Import in the Skills manager. You can select:

• .md file — plain SKILL.md-format file. The # heading becomes the skill name
• .zip bundle — a skill with attached data files. The archive should contain a skill.md and any number of data files (in any directory structure — they are flattened into the skill's file directory)

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.

Exporting

• Export (single skill) — click the upload icon on a skill row:
  • Skill with no files → exports as skill-name.md to Downloads
  • Skill with files → exports as skill-name.zip containing skill.md + all data files
• Export All — exports every skill using the same logic (each becomes either .md or .zip)

Finding Skills to Download

The SKILL.md community has produced hundreds of ready-made skills you can import directly:

• skill0.io — The original SKILL.md marketplace
• skillsmp.com — Agent Skills Marketplace
• agent-skills.md — Community skill directory
• github.com/anthropics/skills — Anthropic's official skill library
• skills.sh — The Agent Skills Directory
• agentskills.io — Agent skills overview and search
• awesome-agent-skills — Curated community list on GitHub

Bash Execution

When enabled, the AI can run shell commands directly on your Mac via /bin/zsh. This lets it read output, run scripts, compile code, check system state, and more — all without leaving the chat.

Enabling Bash Execution

1. Press ⌘, to open Settings
2. Go to the MCP tab
3. Scroll to the Bash Execution section
4. Toggle Enable Bash Execution on

Approval Prompt

When Require Approval is enabled (the default), a sheet appears before each command showing:

• The full command to be run
• The working directory
• A security warning

You can then choose:

• Allow Once — run this command and ask again next time
• Allow for Session — skip the approval prompt for the rest of this chat
• Deny — cancel the command; the AI is told it was rejected

Configuration Options

Working Directory

The directory commands run in (default: ~). Set to your project folder to avoid needing full paths.

Timeout

Maximum seconds a command can run before being killed (default: 30 s). Increase for long-running builds.

Require Approval

Show the approval sheet before each command (default: on). Disable only if you fully trust the AI's judgment for the current session.

Output Limits

To keep the context manageable, output is capped:

• stdout: first 20,000 characters
• stderr: first 5,000 characters

If output is truncated, the AI sees a note indicating how much was omitted.

Example Usage

iCloud Backup

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.

Backing Up

1. Press ⌘, to open Settings
2. Go to the Backup tab
3. Click Back Up Now

The backup file is saved to ~/iCloud Drive/oAI/oai_backup.json. If iCloud Drive is not available, it falls back to your Downloads folder. The date of the last backup is shown in the tab.

Restoring

1. Open Settings → Backup tab
2. Click Restore from File…
3. Select your oai_backup.json file
4. Settings are applied immediately — no restart required
5. Re-enter your API keys in Settings → General

Backup Format

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.

Reasoning / Thinking Tokens

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.

Supported Models

Reasoning is available on models that support extended thinking, including:

• DeepSeek R1 and DeepSeek R1 variants (via OpenRouter)
• Qwen thinking models (via OpenRouter)
• Claude 3.7+ with extended thinking (via Anthropic or OpenRouter)
• OpenAI o1, o3, and similar reasoning models
• Grok reasoning models (via OpenRouter)

Look for the 🧠 badge in the model selector to identify thinking-capable models. Use the 🧠 Thinking quick-filter to show only reasoning models.

Enabling Reasoning

1. Press ⌘, to open Settings
2. Go to the General tab → Features section
3. Toggle Reasoning on

Reasoning only activates when the selected model supports extended thinking (🧠 badge). The setting has no effect on standard models.

Effort Level

The effort level controls how many tokens the model spends on reasoning (as a share of its total token budget):

High (~80%)

Deep, methodical reasoning. Best for math, logic, multi-step planning, and complex coding tasks. More expensive.

Medium (~50%)

Balanced reasoning. Good for most tasks that benefit from thinking (default).

Low (~20%)

Light reasoning pass. Suitable for moderately complex questions without a large token budget.

Minimal (~10%)

Minimal internal thinking — just a quick check before answering. Fastest and cheapest.

Hiding Reasoning Content

Enable Hide reasoning content 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.

In-Chat Experience

When reasoning is enabled and a thinking-capable model responds:

1. A 🧠 Thinking… block appears above the response and auto-expands
2. Reasoning content streams in live as the model thinks
3. When the final answer starts arriving, the thinking block collapses automatically
4. Click the block header at any time to manually expand or collapse it

Anytype Integration

oAI can connect to your local Anytype 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.

Requirements

• Anytype desktop app installed and running
• An API key generated inside Anytype (Settings → Integrations)

Setup

1. Open oAI Settings → Anytype tab
2. Enable the toggle
3. Enter your API key (leave the URL as the default unless your setup is unusual)
4. Click Test Connection — a success message will show how many spaces were found

What the AI Can Do

• Search — find objects by keyword across all spaces or within a specific one
• Read — open any object and read its full markdown content
• Create — make new notes, tasks, or pages
• Append — add content to the end of an existing object without touching the rest (recommended for edits)
• Update — rewrite the full body of an object (use only when truly restructuring content)
• Checkboxes — toggle individual to-do checkboxes by text match, or mark tasks done via their native relation

Example Prompts

• "Search my Anytype for notes about Swift concurrency"
• "Create a new task called 'Review PR #42' in my Work space"
• "Add today's meeting summary to my Weekly Notes object"
• "Mark the 'Buy groceries' checkbox as done in my Shopping List"

Keyboard Shortcuts

Work faster with these keyboard shortcuts.

General

⌘,

Open Settings

⌘/

Show in-app Help

⌘?

Open this Help (macOS Help)

⌘L

Browse Conversations

⌘H

Command History

⌘M

Model Selector

⌘K

Clear Chat

⌘S

Save Chat (re-saves if already named, prompts for name otherwise)

⇧⌘S

Show Statistics

Message Input

Return

Send message (single-line messages)

⇧Return

New line (multi-line messages)

Esc

Cancel generation or close command dropdown

↑ ↓

Navigate command suggestions (when typing /)

Return

Select highlighted command (when dropdown is open)

Settings

Customize oAI to your preferences. Press ⌘, to open Settings.

General Tab

• Add and manage API keys for all providers (OpenAI, Anthropic, OpenRouter, Google, Ollama)
• Switch between providers and set the default model
• Configure streaming, memory, online mode, and max tokens
• Features:
  • Reasoning — enable thinking tokens, set effort level (High / Medium / Low / Minimal), optionally hide reasoning content from chat (see Reasoning / Thinking Tokens)

MCP Tab

• Enable/disable MCP file access
• Add folders via the + Add Folder… button, or drag from Finder
• Enable/disable write, delete, move, and bash execution permissions
• Configure gitignore respect
• Bash Execution — enable AI shell access, set working directory, timeout, and approval behaviour (see Bash Execution)

Sync Tab

Configure Git synchronization for backing up and syncing conversations across devices.

• Repository URL - Git repository URL (GitHub, GitLab, Gitea, or custom)
• Authentication Method - Choose SSH, Password, or Access Token
• Credentials - Enter username/password or access token (encrypted storage)
• Local Path - Where to clone the repository locally (default: ~/oAI-Sync)
• Auto-Save Settings:
  • Enable Auto-Save - Automatically sync conversations
  • Minimum Messages - Only sync conversations with at least N messages
  • Triggers - Sync on app start, idle, goodbye phrases, model switch, or app quit
• Manual Sync:
  • Initialize Repository - Clone repository for first-time setup
  • Sync Now - Full sync (export + pull + import + push)
• Test Connection - Verify repository credentials and connectivity
• Sync Status - Shows last sync time, uncommitted changes, and remote status

Email Tab

Configure AI-powered email auto-responder to automatically reply to incoming emails.

• Enable Email Handler - Master toggle for email monitoring
• Subject Identifier - Filter emails by subject (e.g., [JARVIS], case-sensitive)
• IMAP Settings:
  • Server - IMAP server address (e.g., imap.gmail.com)
  • Port - IMAP port (default: 993 for TLS)
  • Username - Email account username (encrypted)
  • Password - Email account password (encrypted, may need app-specific password)
• SMTP Settings:
  • Server - SMTP server address (e.g., smtp.gmail.com)
  • Port - SMTP port (465 for direct TLS recommended, 587 for STARTTLS)
• AI Configuration:
  • Provider - Which AI provider to use for responses
  • Model - Specific model to use
  • Max Tokens - Response length limit
  • Enable Online Mode - Allow AI to search the web for context
• Rate Limiting:
  • Enable Rate Limit - Prevent excessive email processing
  • Max Per Hour - Maximum emails to process per hour
• Test Connection - Verify IMAP/SMTP connectivity and credentials
• Email Log - View history of processed emails with success/error status

Paperless Tab Beta

Connect oAI to a self-hosted Paperless-NGX instance so the AI can search and read your document archive.

• URL — Base URL of your Paperless instance (e.g. https://paperless.yourdomain.com)
• API Token — Found in Paperless → Settings → API Tokens
• Test Connection — Verify connectivity and display document count

When enabled, the AI can use paperless_search, paperless_get_document, paperless_list_tags, and other tools to interact with your document library.

Beta: Paperless integration is under active development. Some features may be incomplete or behave unexpectedly.

Shortcuts Tab

Create and manage personal prompt template commands. See Shortcuts section for full details.

Skills Tab

Manage SKILL.md-style behavioral instruction files injected into the system prompt. See Agent Skills section for full details.

Appearance Tab

• Adjust text sizes for input and dialog
• Customize UI preferences

Advanced Tab

• Enable/disable streaming responses
• Set maximum tokens (response length limit)
• Adjust temperature (creativity vs focus)
• Configure system prompts (see below)
• Smart Context Selection — Intelligently select relevant messages to reduce token usage
• Semantic Search — Enable AI-powered conversation search using embeddings
• Progressive Summarization — Automatically summarize old portions of long conversations

Backup Tab

One-click backup and restore of all settings to iCloud Drive. See iCloud Backup for full details.

• Back Up Now — exports settings to ~/iCloud Drive/oAI/oai_backup.json
• Restore from File… — imports settings from a backup file
• API keys and credentials are excluded from backups and must be re-entered after restore

Anytype Tab

Connect oAI to your local Anytype desktop app so the AI can search, read, and add content to your knowledge base.

• Enable Anytype — toggle to activate the integration
• API URL — local Anytype API endpoint (default: http://127.0.0.1:31009)
• API Key — generated in Anytype → Settings → Integrations
• Test Connection — verify connectivity and list available spaces

When enabled, the AI has access to these tools:

• anytype_search_global / anytype_search_space — search across all or a specific space
• anytype_list_spaces / anytype_get_space_objects — explore your spaces
• anytype_get_object — read the full markdown body of any object
• anytype_create_object — create a new note, task, or page
• anytype_append_to_object — add content to an existing object without rewriting it (preferred for edits — preserves Anytype internal links)
• anytype_update_object — replace the full body (use sparingly; prefer append)
• anytype_toggle_checkbox — surgically check/uncheck a to-do item by text match
• anytype_set_done — mark a task done/undone via its native relation

Note: The Anytype desktop app must be running for the integration to work. The API is local-only — no data leaves your machine.

System Prompts

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.

What Are System Prompts?

System prompts are special instructions sent to the AI with every conversation. Unlike your regular messages, system prompts:

• Are invisible to you in the chat interface
• Set behavioral guidelines for the AI
• Establish the AI's role, tone, and constraints
• Are sent automatically with every message
• Help ensure consistent, reliable responses

Default System Prompt

oAI includes a carefully crafted default system prompt that emphasizes:

• Accuracy First - Never invent information or make assumptions
• Ask for Clarification - Request details when requests are ambiguous
• Honest About Limitations - Clearly state when it cannot help
• Stay Grounded - Base responses on facts, not speculation
• Be Direct - Provide concise, relevant answers

Note: The default prompt is always active and cannot be disabled. It ensures the AI provides accurate, helpful responses and doesn't fabricate information.

Custom System Prompt

You can add your own custom instructions that will be appended to the default prompt. Use custom prompts to:

• Define a specific role (e.g., "You are a Python expert")
• Set output format preferences (e.g., "Always provide code examples")
• Add domain-specific knowledge or context
• Establish tone or communication style
• Create task-specific guidelines

How Prompts Are Combined

When you send a message, oAI constructs the complete system prompt like this:

Editing System Prompts

To view or edit system prompts:

1. Press ⌘, to open Settings
2. Go to the Advanced tab
3. Scroll to the System Prompts section
4. View the default prompt (read-only)
5. Add your custom instructions in the editable field below

Best Practices

• Be Specific - Clear instructions produce better results
• Keep It Simple - Don't overcomplicate your custom prompt
• Test Changes - Try your prompt with a few messages to see if it works
• Start Empty - The default prompt works well; only add custom instructions if needed
• Avoid Contradictions - Don't contradict the default prompt's guidelines