Cogitae User Guide

Welcome to Cogitae, the self-aware AI conversation platform for macOS. Cogitae is self-aware because the AI has built-in tools to understand and control the application itself—you can ask it to open panels, change settings, search conversations, manage MCP servers, and more using natural language. Cogitae supports multiple AI providers (OpenAI, Anthropic, Gemini, Grok, Mistral, Perplexity, and local Llama.cpp models), lets you switch between them mid-conversation, and helps you organize your work with bookmarks, templates, and branching conversations.

Getting Started

First Launch

When you first run Cogitae, you’ll be directed to the Preferences panel to set up an AI provider.

How-To: Set Up Your First AI Provider

1. In Preferences > AI tab, click the “+” button under “AI Providers”
2. Select your provider type (OpenAI, Anthropic, Gemini, Grok, Mistral, Perplexity, or Llama.cpp)
3. Enter your API key - the Name and Host URL auto-fill based on provider type
4. Wait for the model list to populate automatically (this confirms your API key works)
5. Select your preferred model and click Save
6. Close Preferences by clicking the Preferences icon, New Chat icon, or pressing Escape

Tip: Start with OpenAI, Anthropic, or Gemini if you’re new - they have the simplest setup.

Testing Your Setup

1. Create a new conversation (Command-N)
2. Type a simple query like “Hello!” in the input field
3. Press Command-Enter to submit
4. If successful, you’ll see a streaming response from the AI

Basic Workflow

1. Enter text in the Input message at the bottom
2. Submit via the Submit button or Command-Enter
3. Watch the response stream in with fade effects
4. Continue the conversation - history is retained and sent with each query

Tip: If responses are slow, try a faster model (e.g., GPT-4o-mini instead of GPT-4o, or Claude Haiku instead of Claude Opus).

How-To: Switch AI Providers Mid-Conversation

1. Click the AI provider dropdown in the System message at the top
2. Select a different provider
3. Your entire conversation history is preserved
4. The new provider will respond based on the existing context

Application Modes

Cogitae offers two modes: App Mode (standard window) and HUD Mode (overlay).

App Mode

• Standard macOS window with title bar and traffic lights
• Full menu bar access
• Behaves like any other macOS app
• Can minimize to dock, enter fullscreen
• Other windows can overlap it

How-To: Use App Mode

1. Select “App Mode” in Preferences > Main UI > General > App Mode
2. Restart the app for changes to take effect
3. Use standard window shortcuts (Command-M minimize, Command-F fullscreen)

HUD Mode

• Compact icon in the menu bar
• Click to expand/retract the window
• Always stays on top of other apps
• Dock to any screen edge or corner
• Smooth animations for opening/closing
• Press Command-H to toggle

How-To: Use HUD Mode

1. Select “HUD Mode” in Preferences > Main UI > General > App Mode
2. Restart the app
3. Click the menu bar icon to expand
4. Drag the window to dock it to any screen edge
5. Click the menu bar icon again (or Command-H) to retract

Hibernation: When retracted, queries continue running in the background. Enable notifications in Preferences to get alerts when responses complete.

Ghost Mode: For a transparent overlay appearance, enable Ghost Mode in Preferences > Main UI. This makes backgrounds transparent with thin borders, perfect for overlaying on other content.

Tip: Multi-monitor support - the HUD adapts to the current screen’s visible area, avoiding the menu bar and dock.

Window Layout

Title Bar

Contains:

• Search bar: Search Conversation History
• Preferences icon: Open settings (Command-,)
• Bookmark icon: Bookmark current conversation
• Continue icon: Summarize and continue long conversations
• New Conversation icon: Start fresh (Command-N)

Conversation View

The main scrollable area showing your messages. The Input field is always fixed at the bottom.

Status Bar

Shows system info, errors, and real-time LLM status:

• White text: Normal info
• Yellow text: Warnings
• Red text: Errors

How-To: Navigate Status History

• Use spin buttons (arrows) to browse older messages
• Swipe left/right on trackpad for quick navigation
• Click the info icon for detailed view in a modal sheet
• Click X to clear current message
• Shift-click X to clear ALL status messages

Real-Time Updates: The status bar shows LLM activity like “Executing tool: read_file” or “Searching the web” during AI requests.

Conversations

Creating a New Conversation

• Click the New Conversation icon or press Command-N
• A System message appears with your recent settings

Continuing Long Conversations

When conversations get too long and approach token limits:

How-To: Continue a Long Conversation

1. Click the Continue Conversation icon in the title bar
2. Cogitae generates a summary of the entire conversation using your AI provider
3. A new conversation starts with the summary in the System message
4. All unique attachments and bookmarks are carried over

When to Use: If responses start getting cut off or the AI seems to “forget” earlier context.

Messages

There are five message types in Cogitae:

Input Message

Fixed at the bottom. Never moves.

Toolbar Icons:

• Clear: Remove text and attachments
• Attachments: Add files
• ToC: Open Table of Contents (Command-L)
• Bookmark: Attach bookmarks (Command-B)
• Copy: Copy text to clipboard
• Note: Convert to a Note message
• Submit: Send query (Command-Enter)

How-To: Add Attachments

1. Drag files onto the input area, OR
2. Click the attachments icon and select files
3. Supported: Text files, images, PDFs, audio files
4. Images/audio are base64-encoded; PDFs have text extracted

User Message

Created when you submit a query.

How-To: Edit and Resubmit

1. Click the pencil icon on any User message
2. Edit your text or attachments
3. Press Command-Enter to resubmit
4. A new branch is created, preserving your original

Tip: Editing temporarily hides follow-up responses. Press Escape to cancel and restore them.

AI Message

Contains the LLM’s response. Streams in with fade effects.

Features:

• Edit (creates a branch)
• Bookmark
• Copy
• Branch to explore alternatives
• Collapse/expand

Note Message

Personal annotations that aren’t sent to the AI.

How-To: Create a Note

1. Type your note in the Input field
2. Click the Note icon (instead of Submit)
3. The note is added to your conversation
4. Notes support full markdown rendering

Tip: Bookmark a note and attach it to a query to include it as AI context.

System Message

Appears at the start of conversations. Configures:

• Instruction prompts
• AI provider and model
• Parameters (temperature, max tokens, etc.)
• Web search settings
• Attachments
• Tools
• Workspaces

System Message

The System message is your conversation’s control center.

Instruction Prompts

Select from presets like:

• None: Unrestricted conversation
• Q & A: General assistant behavior
• Code: Code modification with diffs
• Creative Writing: Stories and poems
• Technical Documentation: Docs with structure
• Math/Science: Step-by-step with LaTeX
• Business/Professional: Formal communication
• Translation/Language: With cultural notes

How-To: Create Custom Prompts

1. Go to Preferences > AI > Instruction Prompts
2. Click “+” to add a new prompt
3. Enter a name and prompt text
4. Drag to reorder (up to 20 prompts)

AI Parameters

Adjust model behavior:

• Temperature: Randomness (0 = deterministic, 2 = creative)
• Top P: Nucleus sampling
• Max Tokens: Maximum response length
• Top K: Token selection pool (OpenAI, Grok, Gemini, Llama.cpp)
• Frequency/Presence Penalty: Repetition control
• Stop Sequences: Custom stop tokens
• Reasoning Effort: For thinking models (low/medium/high)

How-To: Adjust Parameters

1. Click the gear icon in the System message
2. Enable checkboxes for parameters you want to set
3. Adjust sliders or enter values
4. Click Save

Reasoning Effort: For models like Claude with extended thinking, o1/o3, Gemini thinking, or Grok with reasoning:

• Low: Fast, cheap (~5K token budget)
• Medium: Balanced (default, ~12K tokens)
• High: Deep thinking, expensive (~25K tokens)

Web Search

Some providers support native web search:

• Supported: OpenAI, Grok, Perplexity, Gemini
• Not Supported: Anthropic, Mistral, Llama.cpp, Custom

How-To: Enable Web Search

1. Click the web search icon in the System message
2. Check “Enable Web Search”
3. Optional: Add allowed domains (restrict to specific sites)
4. Optional: Add blocked domains (exclude specific sites)
5. Click Save

Tip: Domain names are normalized automatically. https://www.example.com/ becomes example.com.

Tool Selection

Tools are displayed in a collapsible section with checkboxes:

How-To: Enable/Disable Tools

1. Click the “Tools” disclosure triangle in the System message
2. Tools are grouped by domain (Cogitae, Filesystem, MCP servers)
3. Check individual tools to enable them
4. Check domain headers to enable/disable all tools in that group
5. The header shows “Tools (X/Y enabled)” when collapsed

Markdown Rendering

Cogitae renders rich markdown with AI-generated summaries.

Supported Elements

• LaTeX: Inline ($E=mc^2$) or block. Shows AI-generated tooltip like “Pythagorean theorem”
• Tables: Render as grids, CSV, or charts (bar, line, pie, area, point)
• Lists: Interactive checklists, AI-summarized
• Code Blocks: Syntax highlighting, diffs, collapse/expand
• Footnotes: Superscripts with hover tooltips
• Headers, Bold, Italic, Links, Images, Horizontal Rules

Interactive Checklists

How-To: Use Checklists

1. In any message, use - [ ] for unchecked or - [x] for checked
2. Click checkboxes to toggle state
3. State persists even after app restart
4. Checked items show strikethrough

Code Block Features

How-To: Work with Code

1. Hover over a code block to show the toolbar
2. Options:
   • Style: Plain, Syntax Highlighting, Diff, Diff with Highlighting
   • Download: Save as file
   • Copy: Copy to clipboard
   • Collapse: Shrink the block
3. Right-click for context menu with all options

Tip: Code blocks with file= directives show the filename and enable advanced diff features.

Diff View

View changes between code versions with color-coded additions and deletions.

LaTeX Tooltips

Hover over equations to see AI-generated descriptions explaining the mathematical concepts.

Table Charts

Tables can be rendered as various chart types for data visualization.

Mermaid Diagrams

Cogitae renders Mermaid diagram code blocks as visual images.

How-To: Create Mermaid Diagrams

Use code blocks with the mermaid language identifier:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

Supported Diagram Types:

• Flowcharts: Process flows with decisions
• Sequence Diagrams: Interactions between components
• Class Diagrams: Object-oriented structures
• State Diagrams: State machines
• Entity Relationship: Database schemas
• Gantt Charts: Project timelines
• Pie Charts: Data distribution

Toolbar Actions:

• Zoom: Resize the diagram
• Copy: Copy diagram code
• Bookmark: Save for quick access
• Save: Export as image file

Tip: Diagrams render asynchronously - you’ll see a placeholder while rendering completes.

Toolbars

Configure toolbar behavior in Preferences > Markdown UI:

• Always On: Always visible
• Always Off: Never visible (use right-click)
• On Hover: Show when mouse hovers
• On Swipe: Show on trackpad swipe

Tools

Tools extend the AI’s capabilities by letting it perform actions.

Tool Categories

Cogitae uses consolidated action-based tools for better efficiency. Each tool supports multiple actions via an action parameter.

Cogitae Tools (Self-Aware)

Let the AI control Cogitae itself:

Filesystem Tools

Work with files on your computer:

Web Tools

Fetch content from the web:

How-To: Use Web Tool

Ask naturally:

“Fetch the content from https://example.com” “Get the markdown version of https://docs.example.com”

The AI can retrieve web content and convert HTML to markdown for easier reading.

Selecting Tools for Conversations

How-To: Enable/Disable Tools

1. In the System message, click the “Tools” disclosure triangle
2. Tools are grouped by domain (Cogitae, Filesystem, MCP servers)
3. Check individual tools to enable them
4. Check domain headers to enable/disable all tools in that group
5. The header shows “Tools (X/Y enabled)” when collapsed

Default: New conversations enable all Cogitae and Filesystem tools by default.

Creating Custom Python Tools

How-To: Create a Custom Tool

1. Go to Preferences > Tools
2. Click “+” under AI Tools
3. Fill in:
   • Name: Tool function name
   • Description: What it does
   • Post-processor: Check if it transforms AI output
   • Parameters: Add with types and constraints
   • Tool URL: Select or generate Python script
4. Save

Import/Export: Drag JSON files to import tools; drag tool names to export.

MCP Servers

MCP (Model Context Protocol) servers extend Cogitae with external tools, resources, and prompts from HTTP services.

Understanding MCP

MCP servers can provide:

• Tools: Functions the AI can call (like web search, database queries)
• Resources: Documents or data to attach to messages
• Prompts: Pre-configured templates

Finding MCP Servers

How-To: Search the MCP Registry

Ask the AI naturally:

“Search for MCP servers that can help with GitHub”

Or use the tool directly:

“Use search_mcp_registry to find web search servers”

The AI will search the official MCP registry and show compatible servers with their descriptions, authentication requirements, and setup instructions.

Adding MCP Servers

Method 1: Natural Language (Recommended)

Ask the AI:

“Enable the GitHub MCP server”

The AI will:

1. Look up the server in the registry
2. Configure it automatically
3. Prompt you for credentials if needed (via a secure dialog)
4. Show discovered tools

Method 2: Manual in Preferences

1. Go to Preferences > MCP Servers
2. Click “+” to add a server
3. Configure:
   • Name: Display name
   • Base URL: HTTP endpoint (e.g., https://api.example.com)
   • Auth Type: Bearer, API Key, Basic, or None
   • Auto-discover: Enable for tools/resources/prompts
4. Click “Test Connection”
5. Save

Security: Only add servers you trust. Always use HTTPS for remote servers.

Managing MCP Servers

How-To: List Configured Servers

Ask: “What MCP servers do I have configured?”

Shows:

• Server name and URL
• Connection status (connected/disconnected/error)
• Capability counts (tools, resources, prompts)

How-To: Disable or Remove a Server

Ask: “Disable the GitHub MCP server” Or: “Remove the GitHub MCP server completely”

• Disable: Keeps configuration for later re-enabling
• Remove: Permanently deletes server and its tools

Using MCP Tools

Once a server is enabled, its tools appear in the System message’s Tools section:

• Grouped under “MCP: server_name”
• Enable/disable like any other tool
• The AI can call them during conversations

Connection Status Indicators

• Green: Connected and ready
• Yellow: Connecting
• Gray: Disconnected
• Red: Error (hover for details)

Cogitae automatically reconnects with exponential backoff.

Workspaces

Workspaces grant the AI access to specific folders on your computer for file operations.

Adding Workspaces

Method 1: Drag and Drop

• Drag folders onto the System message area

Method 2: Select Button

• Click the folder icon in the Workspaces section
• Select one or more folders

How Workspaces Work

When workspaces are configured:

1. The AI receives the list of available paths in its context
2. Tools like tree, glob, grep, read_file can access those folders
3. Security-scoped bookmarks persist across app restarts

How-To: Remove Workspaces

• Click X next to individual paths
• Click Clear All to remove all workspaces

Example Use Cases:

• “Show me the structure of my project” (uses tree)
• “Find all TODO comments in my codebase” (uses grep)
• “Read the main.swift file” (uses read_file)

Security: Only add folders you trust the AI to access.

Table of Contents Panel

Access via Command-L, Input toolbar, or View menu.

List View

Shows all:

• Messages (by role)
• Attachments
• Tools
• Markdown objects (code blocks, tables, equations)

How-To: Navigate

1. Click any row to jump to that item
2. Use the search field to filter
3. Copy/download items directly from the list

Graph View

Visual representation of conversation branches:

• Blue: System messages
• Green: User messages
• Purple: AI messages
• Orange: Note messages

How-To: Use Graph View

1. Switch to Graph mode using the toggle
2. Pan by dragging
3. Zoom with scroll wheel
4. Right-click nodes to:
   • Navigate to message
   • Make branch active (switch conversation paths)
5. Graph auto-fits on load

Tip: Graph view is great for visualizing branching conversations with multiple paths.

Bookmarks

Bookmark conversations, messages, or individual markdown blocks for quick access.

Creating Bookmarks

Conversation Bookmark: Click bookmark icon in title bar

Message Bookmark: Click bookmark icon in message toolbar

Block Bookmark:

1. Hover over a markdown element (code, table, equation)
2. Click the bookmark icon in its toolbar
3. Enter a description

Using Bookmarks

How-To: Open Bookmarks Picker

• Press Command-B, OR
• Click bookmark icon in Input toolbar

Actions in Picker:

• Click to attach as query context
• Click arrow to navigate to bookmark location
• Edit description inline
• Delete bookmarks

Fuzzy Navigation

Bookmarks survive content edits using fuzzy matching:

• Exact hash: Content unchanged
• Context match: Surrounding text matches
• Similarity: Content is similar (>70% match)
• Position fallback: Same type at same position

Tip: Even if you edit a bookmarked code block, Cogitae will find it.

Spotlight Integration

Bookmarks are indexed in Spotlight for system-wide search.

Conversation History

Access via title bar search or Enter in empty search field.

Browsing History

How-To: Find Past Conversations

1. Click the search bar in the title bar
2. Press Enter (empty) to see all conversations
3. Type to filter by content or summary
4. Click a conversation to load it

Special Search Syntax: provider: query

• Example: openai: neural networks - finds conversations using OpenAI about neural networks

Managing Conversations

In the history view:

• Preview ToC/Graph: See structure before loading
• Edit summary: Click summary text to edit inline
• Delete: Remove conversations

Tip: Summaries auto-generate in background if missing.

System Prompt Templates

Save and reuse System message configurations.

Access via Command-T or View menu.

Creating Templates

How-To: Save Current Configuration

1. Configure your System message (provider, parameters, tools, attachments)
2. Open template picker (Command-T)
3. Click “Save Current as Template”
4. Enter a name
5. Template saves: provider, parameters, instruction prompt, web search settings, attachments, tools

Using Templates

How-To: Apply a Template

1. Open template picker (Command-T)
2. Click on a template name
3. All settings apply instantly

Tip: Drag templates directly onto the System message for quick application.

Managing Templates

In the picker:

• Update: Save current config to existing template
• Edit: Change template name
• Delete: Remove template

Templates are searchable in Spotlight.

Exporting Conversations

Export conversations and messages in various formats.

Available Formats

Ask the AI: “What export formats are available?”

Common formats include:

• Markdown (.md)
• Plain text (.txt)
• JSON (structured data)
• HTML (formatted display)

Exporting

How-To: Export Entire Conversation

Ask the AI:

“Export this conversation as markdown”

Or:

“Save this conversation to my Documents folder as a text file”

How-To: Export Specific Message

“Export just the last AI response as markdown”

Preview Before Export

“Preview what this conversation would look like as markdown”

This shows the export content without saving to disk.

Licensing & Account

Cogitae offers subscription tiers that provide access to premium cloud features.

Subscription Tiers

Important: Cogitae never cripples functionality. Expired licenses only affect premium cloud features—your app, data, and local tools always work.

Activating a License

How-To: Activate Your License

1. Open Preferences (Cmd + ,)
2. Click the Account tab
3. Enter your license key (UUID format)
4. Click Activate

Your device is registered and premium features become available immediately.

Viewing Account Status

In Preferences → Account you can see:

• Current tier and status
• License key (masked)
• Expiration dates
• Active devices

Device Management

Each license has a device limit (typically 2-3 devices). To use on a new device:

1. On the old device: Preferences → Account → Deactivate
2. On the new device: Enter and activate the same license key

What Premium Access Provides

• Premium MCP Servers: Full cloud catalog access
• Cloud Plugins: Automatic discovery and updates
• Priority Support: Faster response times

Grace Period

If you’re offline or validation fails:

• 24-hour grace period maintains access
• Reconnecting restores full access
• Your data is never affected

Plugins

Plugins extend Cogitae with additional tools that the AI can use.

What Are Plugins?

Plugins are macOS bundles that provide tools like:

• Code analysis and refactoring
• System command execution
• Database queries
• Custom integrations

Installing Plugins

From the Cloud (Premium):

1. Open Preferences → Plugins
2. Browse the “Available Plugins” section
3. Click Install on the plugin you want
4. Plugin downloads and installs automatically
5. The plugin appears in “Installed Plugins” when complete

Manually:

1. Download the .bundle file
2. Copy to ~/Library/Application Support/us.bitarts.cogitae/Plugins/
3. Restart Cogitae

Managing Plugins

In Preferences → Plugins:

Installed Plugins Section:

• View all installed plugins with version numbers
• See update availability (version shown as “v1.0.0 → v1.1.0” in orange)
• Click Update to install newer versions
• Click the trash icon to uninstall (with confirmation)

Available Plugins Section:

• Browse plugins available for installation
• Incompatible plugins show a warning (“Requires newer app version”)
• Click Install to download and install
• Refresh button checks for new plugins

How-To: Check for Plugin Updates

1. Open Preferences → Plugins
2. Click the refresh button (circular arrow) in the header
3. If updates are available, the “Update” button appears next to installed plugins
4. Click Update to install the new version

Plugin Settings

Some plugins have configurable settings that appear in Preferences → Tool Settings.

How-To: Configure Plugin Settings

1. Open Preferences → Tool Settings
2. Tools with settings are grouped by domain (e.g., “Filesystem”, “Utilities”)
3. Click the chevron (▶) to expand/collapse a tool’s settings
4. Adjust settings using the provided controls (sliders, checkboxes, text fields)
5. Changes are saved automatically

Settings are stored per-plugin and persist across app restarts.

Note: Only tools that define a settings schema appear here. Built-in tools like FileTool and SearchTool typically don’t have user-configurable settings.

Plugin Updates

With premium access:

• Cogitae checks for updates automatically when opening Preferences
• Update notifications appear with version comparison
• One-click update installation
• Progress indicator shows during download

Using Plugin Tools

Once installed, plugin tools appear in the System message’s Tools section:

• Grouped by plugin domain
• Enable/disable like any other tool
• AI can call them during conversations

Tip: After installing a new plugin, start a new conversation or refresh the Tools section to see the new tools.

Preferences

Access via Command-, or the Preferences icon.

Main UI Tab

Appearance:

• Palette: System (auto), System Light, System Dark, Ghost (transparent)
• Tint: Custom color overlay (Ghost mode)
• Opacity: Window transparency (0-100%)
• Blur: Background blur amount (0-50)

Ghost Mode: Makes backgrounds transparent with thin borders. Perfect for overlaying on other content.

Borders: Toggle and adjust thickness (0.1-5.0)

Request Timeouts:

• Standard: Default 120 seconds for regular requests
• Reasoning: Default 900 seconds for thinking models

How-To: Customize Appearance

1. Select a palette
2. For Ghost mode, click tint color well to choose overlay color
3. Adjust opacity and blur sliders
4. Changes preview live

Markdown UI Tab

Element Styles: Customize fonts and sizes for all markdown elements

Code Syntax Theme: Choose from available themes

Toolbar Style: Always On, Always Off, On Hover, On Swipe

AI Tab

AI Providers: Add up to 20 providers

• Select type, enter API key
• Models populate automatically
• Adjust provider-specific parameters

Summarization AI: Select provider for generating summaries (use a fast, cheap model)

Instruction Prompts: Manage up to 20 custom prompts

How-To: Add or Edit Providers

1. Adding: Click “+”, select type, enter API key, models auto-populate
2. Editing: Click edit button, modify settings, save
3. Error Handling: Red border on key field indicates authentication errors

Tools Tab

Python Interpreter: Select version for custom tools

AI Tools: Create and manage Python-based tools

MCP Servers Tab

Manage Model Context Protocol servers (see MCP Servers)

Plugins Tab

Manage external plugin installation and updates (see Plugins)

Installed Plugins: Shows plugins currently installed with version info

• Update button appears when newer versions are available
• Trash icon to uninstall plugins

Available Plugins: Shows plugins available for installation (premium)

• Refresh button to check for new plugins
• Install button to download and install

Tool Settings Tab

Configure settings for plugins that expose configurable options.

How-To: Configure Tool Settings

1. Tools with settings are grouped by domain
2. Click the chevron to expand a tool’s settings
3. Adjust values using the provided controls
4. Changes save automatically

Note: Only tools that define a settings schema appear here.

Account Tab

Manage your Cogitae license and subscription.

How-To: Activate a License

1. Enter your license key (UUID format) in the License Key field
2. Click Activate
3. Your device is registered and premium features become available

Account Information:

• Current subscription tier and status
• License expiration date
• Device management (activate/deactivate devices)

See Licensing & Account for details.

User Tab

Configure personal information to help the AI personalize responses.

How-To: Set Up User Profile

1. Go to Preferences > User
2. Fill in any of the following (all optional):
   • Name: Your name
   • Location: Where you’re located (city, timezone)
   • Interests: Topics, hobbies, or areas of expertise
   • Date of Birth: For age-appropriate context
3. Close Preferences - settings save automatically

Privacy: This information is only sent to the AI when the user tool is enabled. The AI can use it to personalize responses, remember your preferences, and provide location-aware information like local time.

User Information

Cogitae can personalize AI responses using your profile information.

This information is completely optional and is not required to enable full functionality. Cogitae works fully without any user information provided.

Privacy Note: When provided, this information will be sent to your AI Provider as part of LLM requests and becomes subject to their privacy policy and terms of service. This information is not transmitted to or used by BitArts Ltd in any way.

How Personalization Works

When the user tool is enabled, the AI can retrieve:

• Your name and location
• Your interests and expertise areas
• Your age (if date of birth is provided)
• Your current local time

Example Use Cases:

• “What time is it?” - Answers using your local timezone
• “Recommend some activities” - Uses your interests and location
• “Explain this concept” - Adjusts complexity based on your background

Managing Your Information

How-To: Update Profile

1. Open Preferences (Command-,)
2. Click the User tab
3. Edit your information
4. Close Preferences to save

How-To: Clear Information

• Clear individual fields to remove that data
• The AI will only use fields that have content

Tip: You can ask the AI “What do you know about me?” to see what profile information is available.

Keyboard Shortcuts

Global Shortcuts

Conversation Shortcuts

Find Shortcuts

Edit Mode Shortcuts

Natural Language Commands

Cogitae processes commands through the AI, enabling natural requests for app operations.

How It Works

Ask the AI to perform tasks, and it uses Cogitae’s self-aware tools to execute them.

Ephemeral Mode (/# Prefix)

Messages starting with /# enter ephemeral mode - the query and response are displayed but not saved to the conversation history.

How Ephemeral Mode Works:

1. Prefix your message with /# (e.g., /#what's my token usage?)
2. The message is sent to the AI normally with full conversation context
3. The AI response appears as an ephemeral info message
4. Neither the user message nor the AI response is persisted to the conversation
5. The conversation continues as if the exchange never happened

When to Use Ephemeral Mode:

Why Use Ephemeral Mode?

Conversations in Cogitae are persistent and searchable. Sometimes you want to ask the AI something without it becoming part of the permanent record:

• Keep conversations focused: Tangential questions don’t dilute the main topic
• Reduce noise: Operational queries (opening panels, checking settings) stay out of history
• Experiment freely: Try different approaches without cluttering the conversation tree
• Privacy: Sensitive or temporary queries aren’t stored

Note: The /# prefix guarantees ephemeral handling. The AI can also mark its own responses as ephemeral using internal markers for purely operational responses.

Example Commands

Settings You Can Change via Natural Language

Appearance Settings:

• app_mode (hud/app)
• ghost_mode_enabled (true/false)
• blur_strength (0-50)
• tint_opacity (0-100)
• corner_radius (0-20)
• child_border_thickness (0.1-5.0)

Behavior Settings:

• send_notifications (true/false)

Markdown Settings:

• code_style (plain/diff/syntaxHighlighting/diffHighlighting/diffWithHighlighting)
• table_style (table/csv/bar/pie/point/line/area)
• markdown_toolbar_style (alwaysOff/alwaysOn/onHover/onSwipe)
• code_syntax_theme (theme name)

Timeout Settings:

• standard_request_timeout (seconds)
• reasoning_request_timeout (seconds)

Examples:

“Set the code style to diff highlighting” “Change the syntax theme to dracula” “Increase the blur strength to 40”

MCP Server Management via Natural Language

Search for servers:

“Search for MCP servers that can help with GitHub”

Get server info:

“Tell me about the GitHub MCP server”

Enable a server:

“Enable the GitHub MCP server” “Add an MCP server at https://api.example.com”

List servers:

“What MCP servers do I have?”

Disable/remove servers:

“Disable the GitHub MCP server” “Remove the GitHub MCP server completely”

Token Usage

Ask “What’s my token usage?” to see:

• Per-message breakdown: Provider, model, input/output tokens
• Session totals by provider: Aggregated statistics
• Cache breakdown: For Anthropic (cache read/write)

Ephemeral Responses

Operational responses (opening panels, showing usage) are not saved to conversation history. This keeps your conversation focused on actual content.

Advanced Features

Understanding Cogitae Internals

The AI can explain how Cogitae works internally using the app tool with get_internals action.

How-To: Learn About Cogitae’s Architecture

Ask the AI:

“How does Cogitae handle branching conversations?” “Explain how the tool execution system works” “What’s the conversation tree structure?”

The AI can access internal documentation covering:

• Tree-based conversation architecture
• Message flow and AI request processing
• Tool execution pipeline
• Markdown rendering system
• Data persistence model
• MCP integration

Tip: This is useful for understanding why things work the way they do, or for troubleshooting complex scenarios.

Branching Conversations

Explore alternative conversation paths without losing history.

How-To: Create a Branch

1. On any AI, Note, or System message, click the branch icon
2. Add a new message
3. This creates a sibling branch

How-To: Switch Branches

1. Use branch spinners on messages (shows count like “2/3”)
2. Swipe or click arrows to navigate siblings
3. Or use ToC Graph view and right-click > “Make Active Branch”

Attachments

Add files and bookmarks to provide context.

Smart Organization:

• 3+ files from same directory: Auto-grouped by path
• 3+ bookmarks: Grouped into “Bookmarks” section
• Click headers to expand/collapse
• Attachments display side-by-side with wrapping

Supported Types:

• Text files: Sent as-is
• Images: Base64-encoded
• PDFs: Text extracted
• Audio: Base64-encoded
• Bookmarks: Resolved to content

Notifications (HUD Mode)

Get alerts when queries complete while retracted.

How-To: Enable Notifications

1. Go to Preferences > Main UI > General
2. Enable “Send Notifications”
3. Retract HUD while a query is running
4. Get desktop notification when complete

Find in Conversations

Search within conversation text.

How-To: Search

1. Press Command-F to open Find panel
2. Type search term
3. Command-G: Next match
4. Command-Shift-G: Previous match
5. Collapsed messages auto-expand if they contain matches

Troubleshooting

Common Issues

No AI Response

Symptoms: Query submitted but nothing happens

Solutions:

1. Check Status Bar for error messages (red text)
2. Verify API key in Preferences > AI
3. Check internet connection
4. Try a different model

Invalid API Key (401/403 Errors)

Symptoms: Red border on API key field, authentication errors

Solutions:

1. Verify key is copied correctly (no extra spaces)
2. Check key hasn’t expired
3. Verify key has correct permissions
4. Try generating a new key from provider’s website

Slow Responses

Symptoms: Long wait times for AI responses

Solutions:

1. Switch to a faster model (e.g., GPT-4o-mini, Claude Haiku)
2. Reduce conversation length (use Continue Conversation)
3. Check your internet connection
4. Reduce Max Tokens parameter

Truncated Responses

Symptoms: AI responses cut off mid-sentence

Solutions:

1. Click gear icon in System message
2. Enable and increase Max Tokens (e.g., 32000)
3. Some providers have default limits that truncate output

Missing AI Tooltips on Markdown

Symptoms: No tooltips on LaTeX, tables, or code blocks

Solutions:

1. Configure a Summarization AI in Preferences > AI
2. Wait a moment - references generate asynchronously
3. Edit and save the message to regenerate references

Tools Not Working

Symptoms: Tool calls fail or return errors

Solutions:

1. Check Status Bar for execution details
2. For filesystem tools, ensure workspace folders are configured
3. For MCP tools, check server connection status
4. Verify tool is enabled in System message’s Tools section

MCP Server Connection Failed

Symptoms: Red dot on MCP server, tools unavailable

Solutions:

1. Verify server URL is correct
2. Check authentication credentials
3. Ensure server is running and accessible
4. Check for HTTPS requirement (localhost can use HTTP)
5. Click “Test Connection” in Preferences

High Token Usage

Symptoms: Running out of tokens, expensive bills

Solutions:

1. Ask “What’s my token usage?” to identify high-consumption responses
2. Use Continue Conversation to summarize and reduce context
3. Switch to cheaper models for simple tasks
4. Reduce attachment sizes

Colors/Appearance Issues

Symptoms: Colors don’t match system theme

Solutions:

1. Check Preferences > Main UI > Palette setting
2. Ensure macOS appearance isn’t forced
3. Restart app if switching modes

Getting More Help

• Status Bar: Always check for error details
• Click info icon: See full error messages
• Ask the AI: “Help me with [topic]” searches this guide
• Tooltips: Hover over icons for explanations

Quick Reference Card

Most Common Actions

Quick Natural Language Commands

This guide is searchable via Cogitae’s self-aware tools. Ask the AI “help me with [topic]” to search specific sections.

Last updated January 19, 2026