oAI Help & Reference

Getting Started

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

AI Providers & API Keys

You need an API key from at least one provider to use oAI. All keys are stored securely in your macOS Keychain.

Supported Providers

Adding an API Key

Switching Providers

Use the provider dropdown in the header or use slash commands:

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

Shows context length, pricing, and capabilities for the current model.

Sending Messages

Basic Usage

• Type your message in the input field
• Press Return to send
• Press ⇧Return to add a new line without sending

During Generation

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

Retrying Messages

Resends your last message to generate a fresh response.

File Attachments

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

How to Attach Files

• Click the 📎 paperclip icon to browse and select files
• Type @/path/to/file.txt inline 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, source code, logs, etc. (max 50 KB)

Slash Commands

Commands start with / and provide quick access to every feature. Type / to see inline autocomplete suggestions.

Chat Commands

Model & Provider Commands

Conversation Commands

MCP Commands

Shortcuts & Skills Commands

Settings Commands

Memory & Context

oAI features an enhanced memory system with intelligent message selection, semantic search, and automatic summarisation to keep your conversations fast and cost-efficient.

Basic Memory Control

Smart Context Selection

When enabled, oAI intelligently selects which messages to include instead of sending your entire history — reducing token usage by 50–80% while maintaining context quality.

• Always includes the last 10 messages
• Includes starred (important) messages
• Includes high-value messages (detailed content, high cost)
• Respects the model's context window limit

Message Starring

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

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

Semantic Search

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

Progressive Summarisation

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

• Triggers when conversation exceeds threshold (default: 50 messages)
• Older messages (0–30) are summarised into 2–3 paragraphs
• Recent messages (last 20) always sent in full
• Summaries included in system prompt for context
• Cost: ~$0.001 per summary — roughly $0.01/month for heavy users

Online Mode (Web Search)

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

When to Use

• Questions about current events or recent news
• Real-time data (weather, stocks, sports results)
• Information beyond the AI's training cutoff date

How It Works

1. Your question is used to search the web (DuckDuckGo / Google)
2. Relevant results are retrieved
3. Results are added to your message context
4. The AI uses the web results to inform its response

MCP (File Access)

MCP (Model Context Protocol) allows the AI to read — and optionally write — files on your Mac. Ask the AI questions about your own code, documents, and projects.

Setting Up MCP

Read Permissions (always on when MCP is enabled)

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

Write Permissions (optional, disabled by default)

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

For fine-grained control, open Settings → MCP to toggle individual permissions.

Managing Conversations

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

Bulk Delete

1. Open the conversation list (⌘L)
2. Click Select
3. Check the conversations to delete
4. Click Delete (N)

Git Sync (Backup & Sync)

Automatically export conversations as Markdown and push them to a Git repository — free backup and cross-device sync.

Email Handler (AI Assistant)

Monitor an IMAP inbox and let oAI automatically respond to emails with a specific subject tag — your personal AI secretary.

Features

• IMAP monitoring with configurable polling interval
• Trigger by subject tag (e.g. [AI])
• Custom system prompt per inbox
• Rate limiting to prevent runaway costs
• AES-256 encrypted credential storage
• SMTP sending with configurable from-address

Shortcuts (Prompt Templates)

Create custom slash commands that expand into full prompt templates. Build a library of reusable instructions.

Creating a Shortcut

1. Type /shortcuts or open Settings → Shortcuts
2. Click New Shortcut
3. Set a command name (e.g. summarize)
4. Write the prompt template
5. Save — now /summarize is available in chat

Agent Skills (SKILL.md)

Install SKILL.md files that give the AI specialised behavioural instructions — like plugins for the AI's personality and capabilities.

Installing a Skill

1. Type /skills to open the Skills manager
2. Click Install Skill
3. Select a SKILL.md file
4. The skill's instructions are appended to the system prompt automatically

Managing Skills

• Toggle individual skills on/off without removing them
• View the content of each installed skill
• Delete skills you no longer need

System Prompts

System prompts are instructions sent to the AI with every message — they set its personality, tone, and constraints before it sees any user input.

Default System Prompt

oAI ships with a carefully crafted default prompt that emphasises:

• Accuracy First — never invent information
• Ask for Clarification — request details when requests are ambiguous
• Be Direct — concise, relevant answers
• Stay Grounded — base responses on facts, not speculation

Custom System Prompt

Add your own instructions that are appended to the default prompt:

• Define a specific role: "You are a Python expert"
• Set output preferences: "Always provide code examples"
• Add domain context or establish tone

How Prompts Are Combined

Editing System Prompts

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

Settings

Open Settings with ⌘, or by typing /settings.

General Tab

• App theme and appearance
• Font size for the chat interface
• Notification preferences

Providers Tab

• Add / remove API keys for each provider
• Set default provider and model
• Test API key validity

MCP Tab

• Manage accessible folders
• Toggle individual read/write permissions
• Enable gitignore respect

Git Sync Tab

• Repository URL and credentials
• Sync frequency configuration
• Manual sync trigger

Advanced Tab

• Enable/disable streaming responses
• Set maximum tokens (response length limit)
• Adjust temperature (creativity vs focus)
• Configure system prompts
• Smart Context Selection — reduce token usage intelligently
• Semantic Search — AI-powered conversation search
• Progressive Summarisation — auto-summarise long conversations

Keyboard Shortcuts