## 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, German, and French — it follows your macOS language preference automatically.

### Quick Start

1. Add an API key: Press `⌘,` to open Settings, then add your API key for your preferred provider
2. Select a model: Press `⌘M` or type `/model` to choose an AI model
3. Start chatting: Type your message and press `Return` to send

💡 Tip: Type `/` in the message input to see all available commands with autocomplete suggestions.

## 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:

`/provider anthropic` `/provider openai` `/provider openrouter`

## 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

Note: On OpenRouter, dedicated image-generation models (e.g. Sourceful, Seedream, Flux) are fetched from OpenRouter's separate images catalog and merged into the picker automatically — you don't need to configure anything extra to see them.

### 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:

`/info`

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:

`/retry`

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)

💡 Tip: Large text files are automatically truncated to prevent token limits.

## 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:

`/memory on` `/memory off`
Note: Memory state is shown in the header with a badge when enabled.

### 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

💡 Tip: Star key decisions, important information, or context you want the AI to always remember.

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

💡 Provider Priority: 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.

#### 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

Example: Search for "login security methods" to find a conversation titled "Morning Chat" that discussed authentication, even though the title doesn't contain those words.

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

Cost: Each summary costs ~$0.001. For a heavy user (10 summaries/month), this is ~$0.01/month.

### 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

💡 Result: 50-80% token reduction, better context quality, and ability to handle 100+ message conversations efficiently.

## 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

`/online on`

### 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

Note: Online mode is shown in the input bar with a 🌐 badge when active.

## MCP (File Access)

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

⚠️ Security: Only grant access to folders you trust the AI to work with. Review permissions carefully.

### 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

💡 Drag & Drop: 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.

### 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:

`/mcp write on` `/mcp write off`

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

You: "What files are in my project folder?"

AI: (uses MCP to list files) "I found 15 files including src/main.py, README.md..."

## Managing Conversations

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

### Saving Conversations

`/save my-project-chat`

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

`/load`

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)

#### Using Semantic Search

1. Open conversation list (`⌘L`)
2. Type your search query
3. Toggle "Semantic" switch ON
4. Results ranked by relevance

Example: Search "authentication methods" to find conversations about login security, even if the title is just "Chat 2024-01-15".

### Deleting Conversations

`/delete old-chat`

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:

`/export md` `/export json`

Files are saved to your Downloads folder.

## Git Sync (Backup & Sync)

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

💡 What is Git Sync? 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.

### 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

⚠️ Multi-Machine Warning: Running auto-sync on multiple machines simultaneously can cause merge conflicts. Use auto-sync on your primary machine only, or manually sync on others.

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

💡 Use Cases: Customer support automation, personal assistant emails, automated FAQ responses, email-based task management.

### 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

⚠️ Important: Email replies are sent automatically! Test thoroughly with a dedicated email account before using with production email.

### 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

Security Note: All credentials are encrypted using AES-256-GCM and stored securely in your local database.

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

💡 Model Recommendations:

- Claude Haiku: Fast, cost-effective for simple replies
- Claude Sonnet: Balanced quality and speed
- GPT-4: High quality but slower and more expensive

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

⚠️ Case-Sensitive: The subject identifier is case-sensitive. `[Jarvis]` will NOT match `[jarvis]`.

### 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

Incoming Email:

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

    Hi, what are your shipping options?

AI Response (15-30 seconds later):

    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

Technical Details: Email handler uses pure Swift with Apple's Network framework. No external dependencies. Credentials encrypted with AES-256-GCM. Source available on GitLab.

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

💡 Example: Create a `/summarize` shortcut that sends "Please summarize the following text concisely:\n\n{{input}}" — then just type `/summarize` and paste any text after it.

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

With {{input}}:

    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.

Without {{input}}:

    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.

💡 Example: 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.

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

💡 Example use cases:

- `news_sources.json` — a list of URLs for a "Daily AI News" skill
- `search_queries.md` — template search strings for a research skill
- `output_templates.md` — report formats for a writing skill
- `config.yaml` — parameters a skill should follow

#### 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
    ...
    ```

⚠️ Token budget: 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.

#### 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`)

💡 Sharing skills: Zip bundles are the recommended format for sharing skills that include reference data — import the `.zip` directly on another machine to restore both the instructions and all attached files.

### 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

Learn more: Read the SKILL.md open standard article to understand the format in depth, or browse the Anthropic skills repository for high-quality examples.

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

⚠️ Security: 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.

### 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

Note: 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.

### 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

💡 Session Scope: "Allow for Session" resets when you start a new chat, switch models, or load a saved conversation. It is never permanent.

### 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

You: "Run the test suite and tell me what's failing."

AI: (bash approval sheet appears with `cd ~/myproject && swift test`)

After Allow: "3 tests failed: testLogin, testSignup, testLogout. The error in testLogin is…"

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

What is included: All settings and preferences — providers, model defaults, MCP configuration, appearance, advanced options, shortcuts, skills, and more.
What is excluded: API keys, passwords, and other credentials. These are intentionally left out for security and must be re-entered after restoring on a new machine.

### 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

💡 New Mac Setup: 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.

### 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

💡 Tip: Medium effort is a great default. Switch to High for math problems, deep code analysis, or anything requiring careful step-by-step reasoning.

## 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

💡 Tip — Append vs Update: Use append 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. Update replaces the entire body and can degrade rich Anytype internal links (anytype://...) to plain text.

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

## External MCP Servers

Connect any external MCP server that speaks the stdio JSON-RPC protocol (for example `safaridriver --mcp`) and give the AI access to its tools — no custom integration code needed.

### Adding a Server

1. Press `⌘,` to open Settings
2. Go to the MCP tab → External MCP Servers section
3. Click Add Server…
4. Enter a Name (used to prefix its tools, e.g. "Safari" → `safari_navigate_to_url`), the Command to launch it, and any Arguments
5. Click Add — the server starts automatically and its tools are discovered

💡 Tip: Arguments containing spaces can be quoted, e.g. `--root "/Users/you/My Documents"`.

### Server Status

Each configured server shows a status dot and label:

- 🟢 Connected — running and its tools are available to the AI
- 🟠 Connecting… — starting up or performing the initial handshake
- 🔴 Error / Crashed — failed to start or exited unexpectedly
- ⚪ Not started — disabled via the toggle

Toggle a server off/on or delete it entirely with the trash icon. Crashed servers automatically restart up to 3 times with increasing delay (5s, 15s, 30s) before giving up.

Note: Tool names from every external server are prefixed with that server's slug (derived from its Name) so they never collide with oAI's built-in tools or each other.

## Personal Data Tools Beta

Let the AI access your Calendar, Reminders, and Location & Maps to answer questions about your schedule and surroundings. Each service is opt-in and uses Apple's own frameworks (EventKit, CoreLocation, MapKit) with standard macOS permission prompts — nothing goes through a third-party service.

### Enabling a Service

1. Press `⌘,` to open Settings
2. Go to the MCP tab → Personal Data section
3. Toggle on the services you want: Calendar, Reminders, or Location & Maps
4. Click Request Access next to a service — macOS shows its standard permission prompt

### What the AI Can Do

- Calendar — list your calendars and upcoming events, create new events
- Reminders — list reminder lists and items, create new reminders, mark reminders complete
- Location & Maps — get your current location, search for places, geocode addresses, and get directions (all read-only)

⚠️ Write actions require approval: Creating a calendar event or reminder, or completing a reminder, shows an approval sheet first with a plain-language summary of what will happen. Choose Deny, Allow Once, or Allow for Session. Toggle this requirement off in Settings → MCP → Personal Data → Require Approval for Changes.
Note: Contacts support exists internally but is currently hidden while a macOS permission bug affecting hardened-runtime apps is worked out on Apple's side.

### Example Prompts

- "What's on my calendar tomorrow?"
- "Remind me to call the dentist on Friday at 2pm"
- "How far is the nearest coffee shop from here?"

## Research Agents

For tasks that involve searching or reading many files, the AI can spawn several read-only research sub-agents that work in parallel instead of doing everything itself, one step at a time.

⚠️ Cost warning: Each sub-agent runs its own full chain of model calls. A single request that spawns several agents can cost several times a normal reply. Leave this off unless you specifically want that tradeoff.

### Enabling Research Agents

1. Press `⌘,` to open Settings
2. Go to the MCP tab → Research Agents section
3. Toggle Enable Research Agents on
4. Adjust Max Concurrent Agents (1–5, default 3) to control how many sub-agents can run at once

### What Sub-Agents Can Do

Sub-agents are intentionally limited to read-only investigation — they cannot write files, run shell commands, or spawn further sub-agents:

- Read file contents
- List directory contents
- Search for files
- Search the web

Intended for genuinely independent research tasks (e.g. "compare these five files" or "look into three unrelated topics"), not everyday questions — the AI is instructed to reserve this for cases that actually benefit from parallelism.

## Keyboard Shortcuts

Work faster with these keyboard shortcuts.

### General

`⌘,`
  Open Settings
`⌘?`
  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)
- Research Agents — let the AI spawn parallel read-only research sub-agents (see Research Agents)
- External MCP Servers — connect any stdio MCP server for additional tools (see External MCP Servers)
- Personal Data — Calendar, Reminders, and Location & Maps access (see Personal Data Tools)

### 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

💡 Tip: 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.

### 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

⚠️ Security Note: 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.

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

📚 Learn More: For a detailed explanation of system prompts and how they work, see Prompt Engineering on Wikipedia or the OpenAI Prompt Engineering Guide.

### 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:

Complete System Prompt =

1. Default Prompt (always included)
2. + Your Custom Prompt (if set)
3. + MCP Instructions (if MCP is enabled)
4. + Active Agent Skills (if any skills are active)

This combined prompt is sent with every message to ensure consistent behavior.

### 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

⚠️ Important: Custom prompts affect all conversations. Changes apply immediately to new messages. If you experience unexpected behavior, try removing your custom prompt.