## Getting Started

oAI is a powerful AI chat assistant that connects to multiple AI providers including OpenAI, Anthropic, OpenRouter, and local models via Ollama.

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

### Model Information

View details about any model:

`/info`

Shows information about the currently selected model including context length, pricing, and capabilities.

### Default Model

Your selected model is automatically saved and will be restored when you restart the app.

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

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

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

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

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

### Providers Tab

- Add and manage API keys for different providers
- Switch between providers
- Set default models

### MCP Tab

- Manage folder access permissions
- Enable/disable write operations
- Configure gitignore respect

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

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

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