Cogitae Documentation — User Guide for the Native Mac AI Workspace

Cogitae is a native Mac AI workspace built for real work: conversations, files, tools, agents, and automation in one place.

Use this guide to get started quickly, then come back whenever you want to explore more advanced features.

Start Here

If you’re new to Cogitae, this is the fastest path:

1. Launch the app and complete setup.
2. Connect at least one AI provider or local model.
3. Start a conversation and send your first message.
4. Add a workspace folder if you want Cogitae to work with local files.
5. Come back to this guide for tools, agents, memory, MCP servers, and advanced workflows.

Getting Started

First Launch

The first time you open Cogitae, a short setup flow helps you get ready to chat:

1. Welcome — Enter your license key and click Activate. If you don’t have one yet, click “Continue Without License” to use free-tier features. A link to cogitae.ai is included if you want to purchase a key.

2. API Key Setup — Paste one or more API keys into the text area, one per line. Cogitae can auto-detect several providers from key prefixes, including Anthropic, OpenAI, xAI, and Perplexity. Google and MistralAI keys need to be connected manually. A green checkmark appears next to each provider once the connection succeeds. You can also connect a local AI server, such as Ollama at http://localhost:11434. API keys are stored in the macOS Keychain and never leave your machine.

3. Complete — Click “Start Chatting” to begin. The chat input field is focused automatically.

You can reopen onboarding anytime from Help > Getting Started in App mode.

Supported AI Providers

Cogitae works with major cloud providers as well as local models:

Add or remove providers in Preferences > AI. Cloud providers need an API key, local providers need a server URL or local runtime, and each provider needs at least one model.

The Main Window

Two Window Modes

Cogitae offers two window modes, switchable in Preferences > General (takes effect on next launch):

App Mode (default) — A standard macOS window with a title bar, traffic light buttons (close/minimize/zoom), and a Dock icon. Full menu bar with Cogitae, Edit, View, Window, and Help menus. Behaves like any normal macOS application.

HUD Mode — A borderless, floating, semi-transparent overlay window. No title bar, no Dock icon. Instead, a small icon appears in the macOS menu bar (status bar). The window floats above other apps on all Spaces and desktops. Controlled via the status bar icon or keyboard shortcuts.

Window Appearance

All window appearance settings are in Preferences > Appearance and update in real time:

Window Docking (HUD Mode)

In HUD mode, the window is always docked to a screen edge:

• 8 dock states: top, bottom, left, right, upper-left, upper-right, lower-left, lower-right
• Rounded corners: Only on edges not touching the screen boundary
• Edge-locked dragging: Dragging is constrained to slide along the window’s screen edge only
• Center alignment guides: Yellow crosshair lines appear when the window center aligns with the screen center during drag or resize
• Opening/closing animation: The window unfolds from or folds back to its docked edge over 0.3 seconds

Position, size, and dock state persist across launches. HUD and App modes maintain separate positions.

Hibernation (HUD Mode)

Hibernation is the HUD-mode equivalent of minimizing. The app stays running in the background while the window is hidden.

Enter: Click the status bar icon (when window is open), press the global toggle hotkey, or press Cmd+H (when the app is focused). The window folds into its docked edge. Focus returns to the previous app.

Exit: Click the status bar icon again or press the global toggle hotkey. The window unfolds and the chat input gains focus.

Background activity continues: Agents, remote messaging, relay connections, MCP servers, and notifications all keep running during hibernation.

Conversations

Starting a Conversation

Every conversation begins with an instruction message at the top. This message configures which AI provider to use, the system prompt, which tools are enabled, workspace (folder) permissions, and AI parameters (temperature, max tokens, etc.).

Type your message in the input field at the bottom and press Cmd+Enter. The AI response streams in below your message with a busy spinner. When complete, it renders as rich markdown.

Message Types

Hide from LLM

Each user and AI message has a toolbar that appears below the message content. The leftmost button in the toolbar controls whether the message is included in the LLM’s context.

• User messages: The button shows a user icon. Clicking it hides the user message and its AI response from the LLM context.
• AI messages: The button shows an AI icon. Clicking it hides the AI response and its originating user query from the LLM context.

Messages are always hidden or shown as a pair — you cannot hide a user message without also hiding its response, or vice versa.

Visual indicators: When a message is hidden from the LLM, its toolbar icon dims to 30% opacity. Hovering over the button shows a tooltip indicating the current state (e.g., “User Query (Hidden) - Click to unhide”). Hidden messages also display an eye-slash badge on their node in the conversation graph.

Hidden messages remain fully visible in the conversation view — they are only excluded from the context sent to the AI. This is useful for keeping a clean conversation history while removing irrelevant or sensitive exchanges from the AI’s context window.

Branching

Conversations are trees, not linear chats. Every message can have multiple children (branches). The “active path” from root to leaf is what you see and what gets sent to the AI.

Creating a branch: Edit a user message and submit a different version, or click the branch icon (second from the left) on a user message. The old conversation continues as a branch; the new version becomes the active path. You can also edit an AI message directly by clicking its edit button.

Switching branches: A branch popup appears on parent messages that have multiple children. Click the popup to switch between branches. Branches can also be changed in the table of contents outline and conversation graph.

Branch names: Branches are auto-named from the message summary or first line of content (“Branch N” as fallback). Double-click the branch indicator on a user message to rename it.

The Input Field

The input field at the bottom of the conversation area:

• Grows with content as you type (scrollable)
• Shows a placeholder with the current model name: “Ask [model] anything…”
• Press Cmd+Enter to submit, Enter for a newline
• Press Escape to cancel edit mode
• Voice input: Click the microphone button to dictate (requires speech recognition permission)

Input Toolbar Buttons

Instruction Message Controls

The instruction message at the top of each conversation has a toolbar (left to right):

The instruction message body above the toolbar contains:

• Attachments: Files, images, PDFs, bookmarks, or MCP resources attached to the instruction.
• Workspace folders: Directories that tools can access. Drag folders onto the instruction view to add them.
• Tool selection: Expandable checkbox list grouped by domain. Enable or disable individual tools or entire domains.

Prompt Templates

Prompt templates let you save and restore the complete state of the instruction message. A template captures:

• Instruction prompt text and which prompt type is selected (e.g. Agentic, Code)
• AI provider and model
• AI parameters — temperature, max tokens, top-p, top-k, penalties, etc.
• Web search settings — domain filters and toggle state
• Attachments — files, images, bookmarks
• Enabled tools and workspace folders

This makes it easy to switch between different configurations — for example, a “Code Review” template with a code-focused prompt, low temperature, and filesystem tools enabled, versus a “Creative Writing” template with a different provider and high temperature.

Creating a template — Open the template picker from the instruction toolbar and click the + button. A new template is created from the current instruction state. The template appears in the list with a default timestamped name; double-click to rename it.

Loading a template — Click a template in the picker and press the load button. All instruction settings are restored: the prompt text, provider, AI parameters, web search settings, attachments (as new copies), and tool selections. A status message confirms what was applied.

Updating a template — Right-click a template and choose Update to overwrite it with the current instruction state. The template name is preserved.

Renaming a template — Right-click a template and choose Rename, or double-click the name. Press Enter to save or Escape to cancel.

Deleting a template — Swipe left on a template row to reveal the delete button.

The template picker supports search, keyboard navigation, and pagination (50 templates per page). Templates can also be dragged onto the instruction view. The maximum number of templates is 50.

Templates are also accessible programmatically via the Template chat tool, which supports list, get, create, apply, and delete actions. Focus Filters can override the default template when a specific Focus is active.

Attachments

Attach files to messages by:

• Clicking the attachment (paperclip) button in the input toolbar
• Dragging files onto the input field or instruction view
• Using MCP resource browser to attach MCP resources

Supported attachment types: audio, files, images, PDFs, bookmarks, and MCP resources. Attachments appear in a strip at the top of the message with icons, labels, and delete/download buttons.

Conversation History

Access conversation history via the View menu, keyboard shortcut, or by clicking in “Search conversations or press enter for full list” and pressing enter.

• Conversations sorted by creation date with month/year section headers
• Inline title editing (click to select, Return to save, Escape to revert)
• Pagination: loads 50 conversations at a time, more on scroll
• Spotlight search integration for filtering
• Swipe left on a row to reveal a delete button
• Drag a conversation row to Finder to export as JSON

Continuation and Summarization

When a conversation grows long, use “Continue Conversation” (or the AI triggers auto-compaction automatically):

1. All prior messages collapse visually
2. A summary streams in from the AI
3. Attachments and tool references are preserved
4. The conversation continues from the summary point

Auto-compaction preserves the conversation context for continued use.

Undo

Press Cmd+Z to undo text editing operations in the input field or message editors.

Sidebars

Table of Contents / Conversation Graph (Right Sidebar)

Toggle with Cmd+] or Cmd+2. A segmented control in the header switches between three modes:

Graph mode (default): Visual tree diagram of the conversation structure. Each node represents a message. Right-click a node to bring up a context menu with options including “Scroll to” to navigate to that message. Pan and zoom with trackpad or mouse.

List mode: Hierarchical table of contents showing:

• Messages with icons and first-line previews
• Attachments (indented under their message)
• Markdown blocks: headings, code blocks, tables, images (indented)
• Copy button on each block item
• Branch popups on messages with multiple children
• Bookmark badges on bookmarked items
• Collapsible continuation sections

Click any row to navigate to the corresponding message or block.

Bookmarks mode: Browse all bookmarks across conversations with a Spotlight-powered search field for filtering. Each row shows the bookmark type icon, description, and creation date. Click to navigate to the bookmarked item (switching conversations if needed). Right-click for navigate and delete options or swipe left to reveal a delete button. Drag bookmarks from the list onto a message input to attach them. The list updates automatically when bookmarks are created or deleted anywhere in the app.

Agent Panel (Left Sidebar)

Toggle with Cmd+[ or Cmd+1. Shows live agent activity cards. Auto-expands when an agent spawns.

Each card shows: role name, model, elapsed time, progress bar, phase label, token count, continuation count, last tool called, and result/error text.

Card states:

• Running: Blue dot, progress bar, elapsed time ticking
• Pending: Orange dot, “Waiting…”
• Completed: Green dot, fades to 60% opacity
• Failed: Red dot, error message in red
• Cancelled: Gray dot

Click a running card’s status dot to cancel the agent. Click elsewhere on a card to expand/collapse its details. When a card is expanded, a summary of its status output is shown, below that is a log icon which you can click to show the full status output.

Clear completed button (top-right): Removes all finished agents from the panel.

Find and Search

Cmd+F opens a search panel for the current conversation:

• Live match count as you type
• Case-insensitive matching
• Searches rendered text across all visible messages
• Highlights all matches with yellow background
• Expands collapsed messages containing matches
• Cmd+G: Next match (wraps around)
• Cmd+Shift+G: Previous match
• Cmd+E: Use current selection as search text
• Current match flashes with macOS find indicator

Bookmarks

Bookmarks let you save references to conversations, messages, or specific content blocks (code, tables, etc.). Three types:

Access bookmarks in two ways: switch the right sidebar to bookmarks mode (third segment in the segmented control), or open the bookmark picker via the bookmark button in the input toolbar or Cmd+B (App mode). The sidebar bookmarks mode provides an always-visible browser with search, navigation, and drag-and-drop to attach bookmarks to messages.

When navigating to a bookmark, Cogitae loads the conversation (if needed), scrolls smoothly to the target, and highlights it briefly.

Tools

Cogitae has 70+ tools across three categories that the AI can use during conversations.

Native Tools

Stateless file and network operations:

Chat Tools

Self-aware tools that interact with Cogitae itself. These are organized by category:

Conversation and Messages: conversation (create, delete, switch, search, submit queries, manage workspaces), message (list, search, delete, notes, branches, reparent), bookmark (CRUD, picker, ToC), template (CRUD, apply), instruction_prompt (CRUD)

AI and Configuration: ai_config (switch providers, tune parameters per conversation, get/set model scoring), cost (pricing, estimation, comparison with benchmarks), mlx (local model management on Apple Silicon)

Tool and Plugin Management: tool_config (enable/disable tools per conversation, web search settings), tool_optimizer (session-scoped tool activation), plugin_manager (install, uninstall, search cloud catalog), settings (read/modify application settings)

Agent Orchestration: caesar (multi-agent task orchestration with cost-optimized model selection), agent (event-driven agent CRUD, enable/disable, trigger, history), hippodamus (structured task plans with save/load to markdown files), continue_session (request another AI turn), background_task (non-blocking tool execution)

Specialized Agents (premium): aristotle (hypothesis-driven investigation), newton (knowledge research with source evaluation), davinci (creative cross-domain synthesis), patton (adversarial security review — broad audits auto-decompose into parallel domain sub-agents), sherlock (deep project investigation — broad scopes auto-decompose into parallel module sub-agents), socrates (adversarial reasoning audit)

Memory: memory (store, recall, search, list, delete), internal_memory (scoped working memory with note, recall, search, resolve, pin, promote), memory_admin (premium — stats, embedding management, maintenance, deduplication)

System Integration: calendar (EventKit events), reminders (EventKit reminders), contacts (read-only Contacts access), notification (desktop notifications), clipboard (read/write system clipboard), screenshot (list windows, capture window screenshots for AI analysis), app (macOS app control)

Search: academic_search (academic paper search across multiple sources)

User Interaction: ask_user (request user input during tool execution)

UI and Display: show_file (display file contents in chat), window (window management), dashboard (dashboard display)

Export: import_export (conversation export in markdown, Obsidian, or JSON format)

Security: access (check, request, list, revoke directory permissions), secrets (manage Keychain-stored secrets for tool use), exec (locate and run system commands with scoped permissions)

Diagnostics: debugger (inspect agent logs, tool call history, query lifecycle, and debug sessions), status (status bar history)

MCP: mcp (MCP server management)

Execution: wait (timed delay during tool execution), random (random pick from array, random integer, random float)

External Plugins

Loadable plugin bundles that extend Cogitae’s capabilities:

Manage plugins in Preferences > Plugins. Install additional plugins from the cloud catalog or build your own with PluginBuilderPlugin.

Tool Confirmation

Tools have risk levels that determine whether user confirmation is needed:

Confirmation appears as a dialog or desktop notification (for interactive sessions). For headless agents, operations within the agent’s configured workspace are automatically allowed regardless of risk level — the workspace is the security boundary. Operations targeting paths outside the workspace are denied.

Agents

What Are Agents?

Agents are event-driven automations. Each agent binds a system event (timer, file change, clipboard change, etc.) to AI behavior. When the event fires, Cogitae runs a headless AI session using the agent’s configured tools and prompt — no user interaction required.

Event Sources

Action Policies

Each agent has a policy that controls what happens when it triggers:

Configuring Agents

Open Preferences > Agents to manage agents.

Creating an agent: Click “Add Agent”, fill in the name, select an event source, configure the event filter (path patterns for filesystem, schedule for timer, etc.), write an inline prompt, select action policy, and choose which tools the agent can use. You can also import agents from JSON files using the paste or import buttons next to “Add Agent”, or by dropping a .json file onto the agent list.

Exporting an agent: Click the download icon in the editor to save the agent as a JSON file. You can also drag an agent row from the list directly into a Finder folder. Exported agents use the model name instead of internal IDs, so they work when shared with other users.

Importing an agent: Use the paste button (pencil icon) to paste agent JSON, the import button (arrow icon) to open a file picker, or drag a .json file onto the agent list. If the agent specifies a model name, Cogitae automatically matches it to a local provider.

Agent settings:

• Token budget (max tokens per activation, default 10,000)
• Cooldown (minimum seconds between activations, default 60)
• Max activations per hour (default 10)
• Max continuations (auto-continuation limit, default 3)
• Active hours (restrict to specific times and days)
• Provider and model override
• Workspace paths (restrict tool file access). Workspace paths also serve as the security boundary: headless agents can perform any file/fs operation within their workspace without confirmation, but operations outside the workspace are denied.
• Approved executables (pre-approve binaries the agent can run via the exec tool without needing a dialog). Since headless agents cannot show approval dialogs, executables must be pre-approved here or configured as globals in Preferences > Security.

Enable/disable: Toggle the switch on any agent row without opening the editor.

Monitoring Agents

Live agent activity appears in the Agent Panel (left sidebar, toggle with Cmd+[ or Cmd+1). See the Agent Panel section for details.

Agent activation history is available via the agent tool’s history action or in the agent card’s expanded detail section.

Specialized Agents (Premium)

Five named agent personas can be spawned during conversations via their respective tools:

These follow a spawn/result pattern: spawn returns immediately with an agent ID; result blocks until the agent completes. Progress is visible in the Agent Panel. For broad-scope audits and investigations, Patton and Sherlock automatically decompose the work into parallel sub-agents — no manual orchestration needed.

Sub-Agent Orchestration

The caesar tool orchestrates multiple sub-agents with:

• Cost-optimized model selection by task type
• Dependency resolution between agents
• Token budget management
• Rate limit fallback (automatically switches providers on 429/529 errors)

Memory

What Is Memory?

Cogitae maintains persistent semantic memory across conversations. The AI can store facts, preferences, lessons, and project context, then recall them in future conversations.

Memory Categories

How Memory Works

• Storage: The AI stores memories via the memory tool with kebab-case keys and content up to 2,000 characters
• Retrieval: Semantic search using vector embeddings (cosine similarity) or full-text search (FTS5) as fallback
• Injection: Relevant memories are automatically injected into the system prompt at the start of each conversation turn
• Profile memories: Memories flagged as profile are always injected regardless of relevance
• Explicit storage: Only memories explicitly stored via the memory tool are written to the database

Internal Memory

Internal memory is a separate, temporary working memory used by tools and agents. Unlike the main memory system (which is durable and cross-conversation), internal memories are scoped and expire automatically.

Use cases:

• Working notes and intermediate findings during multi-step tasks
• Hypotheses being tested
• Execution state between tool calls
• Coordination notes between agents
• Temporary results from analysis

Scoping: Internal memories are scoped to a conversation, agent session, workspace, or project. Tools and agents can read each other’s memories using scope and source filters, enabling cross-tool and cross-agent coordination.

Actions: note (store), recall (retrieve), search (full-text), resolve (mark done), pin (prevent expiry), promote (elevate to durable memory).

Promotion: Use the “promote” action to elevate an important finding from internal memory to the main durable memory store, making it available across conversations.

Memory Maintenance

Cogitae runs daily maintenance on the memory store:

1. Decay: Unused memories lose relevance over time
2. Consolidation: Similar memories are merged
3. Archival: Low-scoring memories are removed
4. Zombie cleanup and expired memory removal

Configure memory settings in Preferences > Memory:

• Toggle memory injection on/off

The Launcher

A Spotlight-style floating panel for quick one-shot AI queries without opening the main window.

Opening the Launcher

Three global hotkeys (configurable in Preferences > Behavior):

These work from any application, even when Cogitae is not in the foreground.

Using the Launcher

1. Press the launcher hotkey (default Shift+Option+Space)
2. The panel appears in the upper third of the screen
3. Type your question and press Enter
4. A spinner appears while the AI generates a response
5. The full response appears rendered as markdown

Bottom bar (after response): Shows token count, “Open in Cogitae” button (transfers the conversation to the main window), and in inline text mode, a “Copy & Paste Back” button.

Dismiss: Press Escape, click outside the panel, or press the launcher hotkey again.

Inline Text Mode

1. Select text in any application
2. Press Cmd+Shift+Space (or configured hotkey)
3. Cogitae captures the selection (requires Accessibility permission)
4. The launcher opens with the captured text shown as context
5. Type an instruction (“Summarize this”, “Translate to French”, etc.)
6. The AI receives the captured text + your instruction
7. Use “Copy & Paste Back” to paste the response back into the original application

MCP (Model Context Protocol)

Connecting to MCP Servers

Cogitae can connect to external MCP servers that provide additional tools, resources, and prompts.

In Preferences > MCP Servers:

• Click “Add” to configure a new server
• Choose transport: HTTP or stdio (local process)
• For HTTP: enter the server URL
• For stdio: enter the command and arguments
• Configure environment variables and headers as needed
• Click “Test Connection” to verify
• Enable auto-discovery for tools, resources, and prompts

Connection status shows as a colored dot: green (connected), yellow (connecting), gray (disconnected), red (error).

Cogitae supports importing server configurations from Claude Desktop JSON format. You can also drag a .json file onto the server list to import it, or drag a server row from the list to Finder to export it. The server editor has an export button (download icon) to save the current server as a Claude Desktop-compatible JSON file.

Embedded MCP Server

Cogitae itself can act as an MCP server, exposing all of its tools, conversations, and instruction prompts to external MCP clients. This includes chat tools, native tools (file, search, web, SSH, etc.), and any installed external plugin tools.

Enable in Preferences > MCP Servers. Default port: 52532. The server supports both HTTP and JSON-RPC protocols (auto-detected from first byte).

Using MCP Resources and Prompts

When MCP servers are connected:

• MCP resource and prompt buttons appear in the input toolbar
• Click the resource button to browse and attach MCP resources
• Click the prompt button to browse and insert MCP prompts (with argument fields if required)

Markdown Rendering

AI responses are rendered as rich markdown with:

• Headings (h1–h3, deeper levels rendered as h3)
• Code blocks with syntax highlighting (5 display styles: plain, diff, syntax highlighting, diff highlighting, combined)
• Tables (grid view or as charts: bar, pie, point, line, area)
• LaTeX math (inline and display, rendered natively via SwiftMath)
• Mermaid diagrams (rendered via embedded Mermaid engine)
• Interactive checklists (click checkboxes to toggle)
• Footnotes with superscript identifiers
• Images from attachments, file URLs, or remote URLs
• Internal links for cross-referencing within conversations

AI-Generated Block Summaries

Rendered blocks are automatically summarized by the AI and displayed as tooltips. Hover over a block to see its summary. For example, a LaTeX equation might show “Einstein’s mass-energy equivalence” or “The quadratic formula”. Block types that receive AI-generated summaries:

• LaTeX equations — what the equation represents
• Tables — what the data describes
• Lists and checklists — the purpose or topic of the list
• Block quotes — what is being quoted
• Code snippets — what the code does (full files are identified by filename instead)

Summaries are generated once and persisted, so they don’t re-run on subsequent views of the same content.

Block Toolbars

Each rendered block has a toolbar with buttons for:

• Copy: Copy block content to clipboard
• Bookmark: Save a bookmark to this block
• Save: Export block to file (NSSavePanel)
• Download: Download images
• Zoom: Adjust display scale (0.25x to 1.0x)
• Collapse: Toggle block visibility

Code blocks have style popups (plain, diff, syntax, etc.). Table blocks have style popups (table, CSV, bar chart, pie chart, etc.).

Toolbar visibility is configured in Preferences > Markdown. Four styles are available:

Drag and Drop

Drag markdown blocks out of the conversation:

• Code blocks: dragged as text
• Tables: dragged as text/HTML
• Images and Mermaid diagrams: dragged as image files
• Mermaid diagrams also include the code fence text

Security and Permissions

Cogitae uses a layered security model built on macOS sandboxing. Every tool operation is gated by workspace permissions, executable permissions, or secret redaction. Permissions are scoped to prevent cross-context access leaks.

Workspace Permissions

Workspace permissions control which directories the AI and its tools can access on your filesystem.

Granting access: Add workspace folders to a conversation by dragging them onto the instruction message, clicking the Attachments button, or when the AI requests access via the access tool (which presents a folder picker). The selected folder and all its subdirectories become accessible.

Scope: Each permission is owned by a specific context:

A conversation cannot see another conversation’s workspace folders. An agent cannot see a conversation’s folders unless they were granted at a broader scope.

Under the hood: Workspace permissions use macOS security-scoped bookmarks. The app resolves bookmarks at access time and automatically detects stale bookmarks (e.g., if a folder was moved or renamed).

Cleanup: When a conversation or agent is deleted, all its scoped permissions are automatically removed.

Global Workspaces

Global workspaces are directories that are automatically available to every conversation and agent. They are managed in Preferences > Security > Global Workspaces.

Adding workspaces: Use the add (+) button to browse for directories, or drag and drop folders directly onto the Global Workspaces section. Multiple directories can be selected at once.

How they work: Global workspace paths are merged with any per-conversation workspaces. Conversation-specific workspaces take priority (listed first), followed by globals. The AI sees all of them in the Available Workspaces section of the system prompt.

Limits: Up to 20 global workspaces can be configured.

Removing: Swipe left on any workspace row to reveal a delete button, or use the standard macOS swipe-to-delete gesture.

Use case: If you frequently work in the same project directories, adding them as global workspaces saves you from re-adding them to every new conversation.

Executable Permissions

The exec tool allows the AI to run shell commands. Every executable requires explicit user approval before first use.

Approval flow:

1. The AI requests to run a command (e.g., git status)
2. Cogitae resolves the executable path (e.g., /usr/bin/git)
3. If not previously approved, an approval dialog appears with scope options:
   • This conversation/agent only
   • All conversations/agents
   • Global (all contexts)
4. Approving a directory (e.g., /opt/homebrew/bin/) covers all executables within it

Inheritance chain: When checking executable access, Cogitae walks from most specific to most general:

• For conversations: conversation → all conversations → global
• For agents: agent → all agents → global

Headless agents: Event-driven agents run without a UI, so they cannot show approval dialogs. Agents can only use executables that were pre-approved at a scope visible to them (agent, all agents, or global). If an agent tries to run an unapproved executable, the tool call fails.

Stored parameters: Approved executables can have default arguments and environment variables stored with the permission. These are prepended/merged with whatever the AI provides at runtime.

Output redaction: Sensitive environment variables (matching patterns like KEY, TOKEN, SECRET, PASSWORD) are automatically redacted from command output before the AI sees them.

Managing globals: Global executables can be managed in Preferences > Security > Global Executables. You can add executables by browsing, typing a path, or dragging executable files onto the section. Each global executable can be temporarily disabled without removing it, and can have default parameters and environment variables configured.

Secrets

Secrets (API keys, database passwords, tokens) are stored in the macOS Keychain and managed through Preferences > Security.

Key principle: The AI never sees secret values. It only sees secret names. At execution time, tools resolve secret references using the template syntax {{secret:my-api-key}}.

Sensitive content detection: When a tool result contains a value that looks like a secret (matching key names like API_KEY, TOKEN, PASSWORD) but is not already in the secrets store, a dialog appears:

• Add to Secrets — Stores the value in the Keychain
• Allow Access — Session-only access (resets on app relaunch)
• Redact — Hides the value from the AI immediately

Agent access: Headless agents can read secrets via templates but cannot create or modify secrets (no UI for confirmation).

Permission Inheritance

Permissions flow from conversations to their tools and agents, and from agents to their tools:

Conversations → Tools:

• Workspace folders granted to a conversation are available to all tools within that conversation
• Executable approvals scoped to a conversation apply to all tool calls in that conversation
• Secrets are resolved at tool execution time using {{secret:key}} templates

Conversations → Agents → Tools:

• Agents spawned from a conversation inherit the conversation’s workspace paths
• Agents can also have their own scoped permissions (agent, all agents, or global)
• Tools within an agent inherit the agent’s combined permissions
• Agents cannot grant permissions beyond what is visible to them

Interactive conversations can request new workspace folders (folder picker dialog), approve new executables (approval dialog), and create or modify secrets.

Event-driven agents cannot request new permissions (no UI). They rely on pre-approved executables and pre-granted workspace folders at a scope visible to them (agent, all agents, or global). They can read secrets via templates but cannot modify them.

Sub-agents (spawned by the Caesar tool) inherit the parent agent’s workspace paths. Their tool access is filtered to only tools enabled in the parent conversation, and they cannot grant permissions not available to the parent.

On deletion: All scoped permissions are cleaned up automatically when a conversation or agent is deleted. Global and “all conversations/agents” permissions persist.

Network Security

Web requests made by tools and markdown image loading block access to private and internal network addresses to prevent SSRF (Server-Side Request Forgery) attacks. Blocked ranges include localhost, LAN addresses (10.x, 172.16-31.x, 192.168.x), link-local addresses (including cloud metadata endpoints), and multicast. This applies to the web tool, webhook actions, and remote images in rendered markdown. Redirect targets are also validated — a redirect from an external URL to an internal address is blocked.

Preferences

Open Preferences with Cmd+, (or status bar > Preferences in HUD mode).

Sections

Appearance

• Ghost mode: Makes the window fully transparent with only text and controls visible
• Tint color: Color picker for window tint overlay
• Tint opacity: Slider (0–100%) for tint strength
• Blur strength: Slider (0–100%) for the vibrancy/blur behind the window

Behavior

• App mode: Switch between HUD mode (floating, status bar) and App mode (standard window, Dock icon)
• Global hotkeys: Three independent hotkey recorders — app toggle, launcher, inline text
• Network sleep: Keep network connections alive during system sleep for iOS companion access
• Notifications: Send system notifications when hibernating
• Debug logging: Enable self-debugging database logging (see Debugging)

Markdown

• Toolbar style: Controls toolbar visibility behavior
• Element styles: Per-element font and size customization (text, headings, code, etc.)
• Code syntax theme: Dropdown selector for syntax highlighting theme
• Clear markdown cache: Purge the rendered markdown cache

AI

• Token usage: Table showing input/output tokens and cost per provider, with a clear button
• Providers/Models: List of configured AI providers — add, edit, or delete
• Summarization AI: Provider used for auto-summarization
• Default iOS AI: Provider used by the iOS companion app
• Embedding AI: Provider used for memory and plugin embeddings. Changing this re-embeds existing memories and plugin collections
• Extended agent model pool: Allow agents access to all available models
• Instruction prompts: Manage system prompt templates — add custom, reload defaults. Built-in presets:
  • None — no system prompt
  • Agentic — permission-aware autonomous agent with tool discovery and auto-confirmation
  • Code — hands-on coding with epistemic discipline, direct execution, and minimal output
  • Cogitae Debugging — structured self-diagnosis using the debugger tool (agent logs, tool history, query lifecycle, debug sessions/events) and optional sqlite access to Cogitae’s databases. Enforces evidence-before-conclusions: the AI must consult diagnostic tools before reporting findings. Guides the user to enable debug logging in Preferences > Behavior if no data is available
  • Documentation — documentation specialist for technical references and user-facing guides
  • Learning — teaches as it works, explaining trade-offs, patterns, and subtleties inline
  • Marketing — multi-agent marketing orchestrator using sub-agents for research, strategy, and copywriting

AI Provider Editor

When adding or editing a provider in Preferences > AI:

• Name: Display name for the provider
• Type: Provider type (Anthropic, OpenAI, Google, etc.)
• API Key: Stored in macOS Keychain (secure text field)
• Model: The model name to use
• Endpoint: API endpoint URL (auto-configured for cloud providers)
• System prompt: Default system prompt for this provider
• Parameters: Temperature, max tokens, top-p, top-k, penalties (visibility depends on provider type)
• Stop sequences: Add custom stop sequences
• Custom scoring (Llama.cpp/Custom only): Intelligence score, cost, speed, context window for model selection

Keyboard: Escape to cancel, Cmd+Enter to save.

Usage Report

The usage report shows a detailed cost and token breakdown:

• Per-message input/output token counts
• Session totals aggregated by provider
• Estimated cost with cache savings percentage
• Cache performance statistics
• Agent usage breakdown (if agents were used)

MCP Servers

• Embedded MCP server: Toggle to enable the built-in MCP server, with configurable TCP port (0 = auto-assign) and status display
• External MCP servers: List of configured external servers with connection status
• Add server: Manually add an external MCP server
• Paste server: Paste a JSON server configuration
• Upload server: Import server configuration from file

Tool Settings

• Tool context optimizer: Toggle to intelligently enable only relevant tools per query, reducing token usage
• Integrations: Status and setup for Finder Integration (FinderSync extension), Calendar Integration (EventKit access), and Screen Recording (required for the screenshot tool)
• Per-tool configuration: Collapsible domains with individual tool settings editors

Plugins

• Installed plugins: List with version info, update availability, and release notes
• Available plugins: Catalog of downloadable plugins
• Refresh: Check for plugin updates
• Install/Update: Per-plugin download buttons

Agents

• Agent list: View and manage configured agents
• Global limits: Budget cap, max concurrent agents, timeout
• Agent editor: Create or edit agent configurations

Memory

• Inject memories into system prompt: Toggle memory injection on/off
• Memory browser: Searchable table showing key, category, source, access count, injection count, and age — with promote and delete buttons
• Health dashboard: Hit rate, zombie count, database size, last maintenance date, top memories, and at-risk memories

Secrets

Store secrets in Preferences > Security for tools that need credentials (database passwords, API tokens, SSH keys, etc.). Secrets are stored in the macOS Keychain and can be referenced by tools via the secrets tool. Secret values are never exposed to the AI — only secret names are visible.

Sensitive content detection: When a tool result contains a value that looks like a secret (matching key names like API_KEY, TOKEN, PASSWORD) but is not already in the secrets store, a dialog appears with three options:

• Add to Secrets — Saves the value to the Keychain under the detected key name so it is properly managed and redacted going forward
• Allow Access — Lets the AI see the value for the remainder of this session without storing it
• Redact — Hides the value from the AI immediately

This prevents the AI from being blocked by false-positive secret detection while still protecting genuinely sensitive values. The “Allow Access” choice is remembered for the session and resets when you relaunch the app.

Account

• License key: Secure text field with Activate/Deactivate buttons
• Refresh license info: Force server validation of current license
• Tier: Displays current license tier (Free, Trial, Paid)
• Status: Activation status (Active, Limited, Not activated)
• Expires: License expiration or trial end date
• Upgrade/Purchase: Buttons for trial-to-paid or free-to-paid upgrade
• Active devices: List of licensed devices with device info and revocation controls

About

• Version: Version number and build number
• Build date: Compile date
• Reveal data folder in Finder: Opens the ~/.cogitae/ directory
• Acknowledgements: List of third-party libraries with links

iOS Companion App

Cogitae has an iOS companion app that acts as a thin client — no AI runs on the iOS device. All AI processing happens on your Mac.

Connecting

The iOS app discovers your Mac via two methods:

• LAN (Bonjour): Automatic discovery on the same network. No setup required.
• WAN (Relay): Through the Cogitae relay server with end-to-end encryption (Curve25519 ECDH + AES-256-GCM). Enable in Preferences > Remote Access on the Mac.

If both are available, the app uses both simultaneously (the Mac deduplicates messages).

Network Sleep Behavior

By default, Cogitae keeps network connections alive when the system goes to sleep, allowing the iOS companion app to reach your Mac even while the display is off. This uses a process activity assertion to prevent idle system sleep from suspending the relay and Bonjour connections.

To disable this, uncheck Keep network connection when system is sleeping in Preferences > Behavior > Network. When disabled, the Mac will sleep normally and network connections will drop until the system wakes.

Features

• Conversations: Browse Mac conversations with search filtering, create new ones, send messages, view responses
• Branch navigation: View and select conversation branches
• Agent dashboard: View, start, stop, and run agents on any connected Mac
• Agent questions: Answer agent ask_user questions remotely
• Push notifications: Silent push for background message delivery
• Multi-Mac: Tab-per-Mac interface for managing multiple Macs

License Sync

The iOS app syncs your license from the Mac via iCloud Key-Value Storage. The Mac writes the license token; the iOS app reads and activates it.

Finder Integration

The FinderSync extension adds a Cogitae submenu to Finder’s right-click context menu:

Enable in Preferences > Tool Settings > Integrations, or in System Settings > Privacy & Security > Extensions > Cogitae.

Shortcuts and Siri

Cogitae provides 18 App Intents for Shortcuts, Siri, and Spotlight:

AI Intents

Data Intents

UI Intents

Focus Filters

Cogitae supports macOS Focus Filters, allowing you to override the default provider, template, instruction prompt, ghost mode, and tool optimizer when a specific Focus is active.

macOS Services

Three services available from any app’s Services menu:

URL Scheme

Other apps can trigger Cogitae via the cogitae:// URL scheme. URLs use a generic tool dispatch format: cogitae://<tool_name>/<action>?param1=value1&param2=value2. The host maps to the chat tool name, the first path component is the action, and query parameters become tool arguments. This provides URL-scheme access to all 51 registered chat tools.

x-callback-url Support

Callers can include x-success and/or x-error query parameters to receive results via callback URLs:

cogitae://conversation/list?limit=3&x-success=myapp%3A%2F%2Fhandle-result

On success, Cogitae opens: myapp://handle-result?result=<url-encoded-result> On error: myapp://handle-error?errorMessage=<url-encoded-error>

Without callbacks, results are posted to the status notification feed.

Chaining example — run app/info, then post the result as a status notification:

cogitae://app/info?x-success=cogitae%3A%2F%2Fstatus%2Fpost%3Fmessage%3Dcallback-success%26category%3Dsuccess

Status Bar

The status strip at the bottom of the window provides:

Activity Dot

A colored circle showing current state:

• Green: Idle
• Blue (pulsing): Thinking or streaming
• Orange (pulsing): Tool executing
• Purple (pulsing): Agent running
• Red (pulsing): Error

Token and Cost Display

Right side shows cumulative tokens and estimated cost for the current conversation (e.g., “847 tokens / $0.0012”). Updates in real time during streaming.

Notification Badge

Red badge on the right shows unread notification count (hidden when zero, caps at “99+”).

Notification Feed

Click the status strip to open the notification feed panel. Shows all recent events with category icons, timestamps, and messages:

• Green checkmark: Success
• Gray info circle: Information
• Yellow warning triangle: Warning
• Red X circle: Error
• Purple CPU: Agent activity
• Orange hammer: Tool execution

Click a notification with details to expand it (up to 3 lines of detail text). Opening the feed marks all notifications as read.

Keyboard Shortcuts

Global (work from any app)

When Cogitae Is Active

App Mode Only (View Menu)

Data Storage

All data is stored locally on your Mac:

There are no remote databases. Everything stays on your machine.

License System

Cogitae uses a license-key-only authentication model (no user accounts or passwords).

License Types

License Key Format

CGTA-XXXX-XXXX-XXXX-XXXX

Debugging

Cogitae has a built-in self-debugging system that logs detailed information about conversations, tool calls, agent operations, and query lifecycles to SQLite databases. This gives the AI deep insight into how things ran, what went wrong, and where.

Agent Logging

Agent logging is on by default and is managed separately from debug logging. To configure it:

1. Open Preferences > Agents
2. Under “Agent Logging”, toggle Enable agent logging

The setting takes effect immediately. Disabling it erases the agent log database immediately.

Debug Logging

Debug logging is off by default because it uses disk space. To enable it:

1. Open Preferences > Behavior
2. Under “Debug Info”, check Enable self-debugging database logging

The setting takes effect immediately — no restart is required. Disabling the setting erases all debugging databases immediately.

When enabled, three databases are populated:

All debug and agent log data is automatically cleaned up after 7 days.

The Debugger Tool

The debugger tool lets the AI inspect its own operational history. It supports five actions:

Typical use: When something goes wrong with an agent or tool execution, ask the AI to investigate. With the relevant logging enabled, the debugger tool can trace exactly what happened — which tools were called, what parameters were passed, what errors occurred, and how the query lifecycle progressed.

Requirements: The debugger tool must be enabled in the conversation’s tool selector. Agent log inspection requires agent logging (Preferences > Agents). Tool history, query history, and debug session inspection require debug logging (Preferences > Behavior).

Troubleshooting

The AI is not responding

• Check that your API key is valid in Preferences > AI
• Check the status strip for error indicators (red dot)
• Click the status strip to view error details in the notification feed
• Try switching to a different provider

Tools are not available

• Check tool enablement in the instruction message’s tool selection
• Some tools require workspace paths to be configured
• Some tools require a premium license

Agents are not firing

• Check that the agent is enabled (toggle switch in Preferences > Agents)
• Check active hours configuration
• Check cooldown and rate limit settings
• Verify the event source configuration (correct paths, valid schedule)
• Check the Agent Panel for error details

Specialized agents not working as expected

Specialized agents (Aristotle, Newton, Da Vinci, Patton, Sherlock, Socrates) and sub-agents spawned by Caesar each request a set of base tools. These tools are intersected with the tools enabled in the parent conversation — any tool not enabled in the conversation is silently dropped. If a specialized agent seems unable to perform its role, check that its required tools are enabled.

All agents also receive continue_session and hippodamus automatically. Caesar is always removed from sub-agent tool sets to prevent recursive spawning.

To enable tools: Click the tool selector in the conversation’s instruction message and enable the required tools. You can also pass additional tools via the extra_tools parameter when invoking a specialized agent.

Why tools are filtered: Sub-agents inherit their parent’s tool boundary as a security measure. A sub-agent cannot access tools that the parent conversation or agent has not enabled.

Hotkeys not working

• Verify hotkeys are enabled and configured in Preferences > Behavior
• For inline text capture, grant Accessibility permission when prompted
• Carbon hotkeys do not require Accessibility permission

iOS app not connecting

• LAN: Both devices must be on the same network
• Relay: Enable Remote Access in Preferences on the Mac; requires a paid license tier
• Check relay status in Preferences > Remote Access

Memory not being used

• Ensure memory injection is enabled in Preferences > Memory
• Check that the memory store is not empty (use memory browser)

MCP servers not connecting

• Check connection status dots in Preferences > MCP Servers
• For stdio servers, verify the command exists in PATH
• Click “Test Connection” in the server editor
• Check that the server is running and accessible

Sandboxing problems

Cogitae runs in a macOS sandbox. This affects several behaviors:

• HTTP connections to LAN hostnames fail: URLSession may reject plain http:// requests to hostnames like http://myserver:9111 with a misleading “Internet connection appears to be offline” error (NSURLErrorDomain -1009), even though the network is fine. Use the IP address instead (e.g., http://192.168.1.2:9111). This commonly affects MCP servers running on other machines on your local network.
• Home directory path: Under sandbox, FileManager.default.homeDirectoryForCurrentUser returns the container path, not the real home directory. Cogitae uses AppDelegate.realHomeDirectory (POSIX getpwuid) for paths that must match real filesystem locations like ~/.cogitae/.
• Database paths: All SQLite databases are stored in the sandbox container at ~/Library/Containers/us.bitarts.cogitae/Data/Library/Application Support/us.bitarts.cogitae/, not the unsandboxed Application Support directory.
• Plugin quarantine: Plugin bundles may retain the quarantine extended attribute under sandbox, causing Gatekeeper to block them. See Preferences > Plugins for status.

Last updated March 23, 2026