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.

Cogitae doesn’t resell AI usage. You bring your own API keys and pay providers directly at their rates, or run local models at no cost.

Use this guide to get started quickly, then come back whenever you want to explore more advanced features. To see what changed in each release, read the changelog.

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; they are shown masked. Cogitae recognizes Anthropic, OpenAI, OpenRouter, DeepSeek, xAI and Google Gemini keys by their prefixes and shape, and checks a key with no known prefix with MistralAI and DeepSeek. A key the provider rejects is listed under the text area instead of being added. Labels such as ANTHROPIC_API_KEY= and quotes are ignored. A green checkmark appears next to each provider once the connection succeeds. Each key becomes an account whose models are ready to use with no further setup, and Cogitae picks a default model for new conversations: the cheapest of your providers’ models that is at least as capable as the middle of the range (OpenRouter’s models are not counted). You can also connect a local AI server, such as Ollama at http://localhost:11434. API keys are stored in the macOS Keychain and are sent only to the provider they belong to, never to BitArts.

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 accounts in Preferences > AI. An account is one API key (cloud) or one server (local), and you can have several of one type, such as a work and a personal key. Every model an account serves can be picked in a conversation, with no model to set up. Cloud model lists come from Cogitae’s model catalog, which lists each model once even when the provider serves it under several names; local servers list their own models. Preferences > Models shows every model and which ones agents may pick.

When a Model Is Retired

Providers retire models. A retired model drops out of the model lists once its date has passed. For your default model and the models agents may use, Cogitae also warns you rather than changing anything:

• A warning notification names the account, the model, and a suggested replacement.
• When a provider has announced a retirement date, you are warned ahead of time with the date and the provider’s suggested successor.
• If the provider rejects the model mid-conversation, Cogitae offers to switch the conversation to a live model from the same account, carrying over that model’s settings. Nothing changes unless you accept.

Agents are different: they pick their own model, so a retired one is replaced automatically and the agent keeps running.

When Claude Declines a Request

Newer Claude models run safety checks that occasionally decline a request, including harmless security or life-sciences work. When that happens, Anthropic answers with another Claude model instead (for example, Claude Opus 4.8 for security topics), and the status bar says which model declined and which one is answering. If the decline came partway through a reply, the second model carries on from where the first stopped. You pay each model’s own rate for the part it wrote, and nothing for a model that declined before writing anything.

If no other model can answer, or the one that would is busy, Cogitae shows that the request was declined and why, and names the model to try if one was busy.

The Main Window

Two Window Modes

Cogitae offers two window modes, switchable in Preferences > Appearance (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 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, but the AI can’t read them anywhere: they are left out of the context sent to the AI, out of what the AI’s tools return (listing, searching or summarizing messages and conversations, which name a hidden message without its content), out of conversations read over MCP, and out of the conversation’s generated title. 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. Switching to a branch also switches the model picker to the model that answered last in that branch, so a follow-up goes to the same model.

Branch names: A branch is named from its message summary, or “Branch N” when there is none. Double-click the branch indicator on a user message to rename it. The same name appears in the branch popup, the table of contents and the iOS app.

For branching used over several sittings, with one branch per topic, see the interview prep tutorial.

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 model 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, model, 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 paging. Templates can also be dragged onto the instruction view. You can keep up to 50 templates.

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
• From an MCP client such as Claude Code: the conversation tool’s submit_query action takes attachments, a list of base64 data URIs (data:<mime>;name=<file>;base64,<data>)

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.

Files must be text or code, images, PDFs, or audio. Other files, such as .zip archives or apps, are refused with a message because a model can’t read them; to send an archive, unzip it and attach the files inside. Images, audio, and other files attached to the system message aren’t sent, because a model’s system prompt takes only text, and a warning says so; attach them to a user message instead.

How an attachment reaches the model depends on what the model accepts. PDFs are sent as the file itself to models that read PDFs (Claude, Gemini, and current GPT models), so layout, tables, charts, and scanned pages come through; other models receive the PDF’s extracted text. An image or audio file sent to a model that cannot take it is left out, the model is told so, and a warning appears in the status bar. Gemini models and Mistral’s Voxtral models receive audio attachments directly.

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
• Right-click a conversation for Edit Title (rename it in place: Return saves, Escape reverts), Copy Title and Export
• 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; a message that starts a branch shows the branch name after its role. The graph fills the sidebar’s width (shrinking to show several branches side by side) and opens on the newest messages. Click a node to go to that message; right-click it for more options. Drag or scroll to pan; pinch, or scroll with Shift held (a mouse wheel works too), to zoom.

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, total cost (once the agent completes), 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. Their runs stay in each agent’s history.

Run an agent button (left of Clear completed): Drops down a list of your agents, each with a play button that runs it immediately. Click the button again to roll the list back up.

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

The AI can use three kinds of tools during conversations: native tools, chat tools and external plugins.

The AI remembers the tools it used in earlier replies — which tool it called, with what arguments, and what came back — even after you switch to a model from another provider. This history is kept out of the chat; you see only the replies. When a conversation’s tools are turned off, the history is not sent.

Native Tools

Stateless file and network operations:

Chat Tools

Self-aware tools that interact with Cogitae itself. Twelve of them need a Paid license or an active trial: caesar, hippodamus, the six specialized agents, memory, internal_memory, memory_admin and academic_search. Without a license, tool_config lists an enabled tool that needs one as “Yes (needs a license)”, and the AI is told it is unavailable rather than working around it. If the AI calls a tool that doesn’t exist, Cogitae stops the reply and says so in the conversation and the status strip. They 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 (list accounts and models, switch the conversation’s model, tune parameters per conversation, get/set a model’s custom 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, export and import of agent files), hippodamus (structured task plans with save/load to markdown files), continue_session (request another AI turn), background_task (non-blocking tool execution)

Specialized Agents: 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 (stats, embedding management, maintenance, deduplication)

System Integration: calendar (Calendar events), reminders (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, debug sessions, and requests from the iPhone app), 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.

A plugin runs inside Cogitae with all of its access. Before loading one, Cogitae checks its signature: plugins signed by BitArts (the bundled ones and the catalog’s) load; any other, such as one built with PluginBuilderPlugin, asks first and is remembered per build. Only BitArts-signed plugins can read your AI accounts’ API keys. Plugins declare the risk of each call, and one that doesn’t counts as moderate. AppleScript runs a script without asking only if every app it targets was allowed with Always Allow and it uses no commands outside them (do shell script always asks).

Maintenance Toolkit

The Maintenance Toolkit plugin (install it from Preferences > Plugins; it needs a Paid license or a trial) lets Cogitae find out where your disk space went and clean it up. Ask in plain words, for example “My Mac says its disk is almost full. Find out what’s taking up the space and help me clean it up.”

• The first time, Cogitae asks for access to your home folder: the folder panel opens with it selected, and you click Grant Access.
• It measures what takes the space: old installers and disk images, caches, build folders such as Xcode’s DerivedData, and data left behind by apps you’ve removed.
• It separates what’s safe to delete from what needs your judgment, and leaves your own files (photos, videos, documents) alone unless you tell it otherwise.
• Nothing is deleted without a confirmation dialog that lists what goes and its size. Files go to the Trash first; emptying the Trash asks again and can’t be undone.
• Cache and log folders are emptied, not removed, and a file in use is skipped without stopping the rest. /tmp is left alone: running programs keep live files there.

Its other tools find duplicate and old files, list apps you don’t use, show browser cache sizes, list and turn off startup services, and clear privacy permissions left by apps you’ve removed.

Tool Confirmation

Every tool call has a risk level:

Choose the threshold in Preferences > Tool Settings > Ask before: Destructive operations only (the default) or Anything that changes something. Operations that change Cogitae itself always ask, and their dialog has no “Allow All”.

Approval dialogs, including the one for running a program, name who asks (the AI, an MCP client such as Claude Code, or an app that opened a cogitae:// link) and show the arguments. Allow All Similar allows the same tool and action for the rest of the session. For files it covers only their folder (hover the button to see which), and it is not offered for the home folder or above. When Cogitae is in the background you also get a notification; clicking it brings the dialog forward.

Headless sessions (event agents and their sub-agents, where no one can answer a dialog) never ask. There:

• Anything that changes Cogitae is refused.
• A file operation outside the agent’s workspace folders is refused, whatever its risk.
• A file operation inside them runs, even if destructive: the workspace is the agent’s pre-approved area.
• Anything else at or above the threshold is refused.

Sub-agents started from a chat (Caesar, Sherlock, Patton…) are not headless: their dialogs appear in the chat that started them.

Only tools enabled in the conversation run, however the AI names them. Tool results reach the AI marked as data, and the AI is told never to follow instructions found in them (a web page or file that says “ignore your instructions” is just text).

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:

Ask First applies to every automatic start, including the AI’s agent trigger. Run Now in Preferences and a tap on the iPhone count as your approval and start the run at once.

Each run is limited by the agent’s token budget (prompt and completion tokens of every request in the run; 1,000,000 by default). A run that spends it stops and says so in its result. Sub-agents the run starts aren’t counted against it.

Configuring Agents

Open Preferences > Agents to manage agents.

Creating an agent: Click the + button (Add new event 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 an agent from a file or from the website (see Agent Files).

When an agent can’t finish: An agent that gives up on its task (a model it needs is unavailable, a step it can’t do) says so at the start of its final reply, and the run is shown as failed with its reason, not as succeeded.

Running an agent now: Click the play button on an agent’s row, or in the editor, to run it once right away instead of waiting for its event: useful to see what a timer agent does, or to try an agent before turning it on. The run uses the agent’s prompt, tools, model, token budget and action policy (its result is shown as usual; an Ask First agent runs without asking, since the click is the approval). It skips the checks that decide whether an event starts the agent: it runs even if the agent is off, outside its active hours or cooling down. A file, calendar or other event agent is told that no real event happened. The editor’s button runs the saved agent, not unsaved changes.

Agent settings (the editor shows a short hint under each limit):

• Max tokens: the longest single reply the model may write (empty uses the model’s default). It does not limit the whole run
• Token budget: the total tokens one run may use, input and output, across every model call (default 1,000,000). The run stops when it is spent. Each call resends the conversation, so long runs use it quickly; the tokens of sub-agents it starts count too
• Cooldown (minimum seconds between activations, default 60; 0 for none). A timer agent whose cooldown equals its interval runs on every tick
• Max activations per hour (default 10)
• Max continuations: how many times a run may carry on in a fresh turn before it has to stop (default 3). An agent with a tool list gets the continue_session tool for this automatically; add it to the disallowed tools to turn continuing off
• Active hours (restrict to specific times and days; the same start and end hour, such as 0–0, means all day)
• Model: a fixed model, or Choose Automatically (see Choosing the model below)
• 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.

Choosing the model: The editor’s Model popup either fixes the model the agent runs on, or is set to Choose Automatically. Then, at each activation, Cogitae picks the cheapest model checked for agents in Preferences > Models that suits the task, within these settings:

• Task Type: the kind of work (Any, or one of eight task types such as code generation or agentic work); the model must meet that task’s minimum intelligence score, and its coding or agentic score where the task calls for one and the model has been measured
• Min Intelligence: the lowest intelligence index (0–100) the model may have
• Accounts: which of your accounts the agent may use (All Accounts when none is checked)
• Max Price: the highest blended price in dollars per million tokens (three parts input to one part output). Local models count as free; a cloud model with no known price is not used under a price limit

Accounts and Max Price are hard limits: no model outside them is used, not even as a fallback, and if none is available the activation fails. They also bind every sub-agent the agent starts (Caesar, Sherlock, Patton and the other specialized agents) and their sub-agents, which cannot be switched to a model outside them. With the agent tool an agent can also be limited to account types or to a list of models. Choosing a fixed model clears the task type and minimum intelligence; the limits stay, for the agent’s sub-agents.

Automatic selection skips a model whose context window is too small for the agent’s prompt and tools, a local model whose server cannot call tools when the agent uses tools, and a llama.cpp server that does not answer. Local models are not picked over cloud models: they are used when an agent is limited to local accounts, when there is no cloud account, or as the last resort. When no scored model fits, the agent falls back to the default model (a sub-agent to its parent’s model), and as a last resort to a local model — one the server has loaded first — whose minimum scores are ignored. An agent limited to local accounts may use any model the server lists; otherwise only checked models are used.

When a model fails: If a model is rate limited and the wait is a minute or less, the agent waits and tries it again. Otherwise it switches to another model. A rate limit rules out that account, since the limit belongs to its API key, but another account of the same provider can still be used; a retired or unknown model, or rejected credentials, rules out that model for a day. Up to three other models are tried. Sub-agents do the same, falling back to their parent’s model when no scored model fits. To make a ruled-out model selectable again, ask the AI to clear the list of ruled-out models.

Flex processing (OpenAI, Gemini): Agents that run on an OpenAI or Gemini model use the provider’s Flex tier, which costs half as much but can reply more slowly. Chats and sub-agents are not affected. If the provider has no Flex capacity at the moment, or the model has no Flex tier, the request is sent at the standard price instead; after a capacity refusal, that provider’s agents stay on the standard tier for 10 minutes. To turn Flex off, clear “Use Flex processing for agents” in the account’s settings (Preferences > AI).

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

Agent Files

An agent can be saved as a file, shared, and added on another Mac. Agent files are JSON in a documented format, so they can also be written by hand or by an AI. Ready-made agents are on the website at cogitae.ai/agents.

Exporting: Click the download icon in the editor, or drag an agent row into a Finder folder. The agent tool’s export action returns the same file.

Importing: Paste a file with the paste button (pencil icon), choose one with the import button (arrow icon), drag a .json file onto the agent list, or click “Add to Cogitae” on the website. The agent tool’s import action does the same with a file’s text or a website link. Files exported by earlier versions of Cogitae still import.

Importing never saves anything. It opens the editor with a new agent, turned off, and a summary above its fields:

• What starts the agent, and its action policy (flagged when the agent acts without asking first)
• Tools that can delete, move or overwrite, or change Cogitae, and a warning when the agent may use every tool (a Notify Only agent’s tools only read, so none is flagged)
• Tools that are not installed, which are removed from its tool list
• A model none of your accounts serves; the model is then chosen automatically
• Folders the agent needs. Each is shown in orange with a grant button that opens the folder picker at that folder: pick it, or another folder, to give the agent access. A folder you don’t grant is kept, but the agent can’t use it

Check the agent, save it, then turn it on. An agent limited to accounts (by name) that you don’t have can’t be imported, since dropping them would widen the limit. A file of a newer version asks for a newer Cogitae. Only links to cogitae.ai can add agents.

What a file holds:

Paths under your home folder are written as ~/... and point to the same place in the home folder of whoever imports the agent. A file leaves out whether the agent is on, its folder grants, and anything tied to one Mac, such as account ids. Fields Cogitae doesn’t recognize are ignored. A JSON Schema for checking a file is on the website.

{
  "format": "cogitae-agent",
  "version": 1,
  "name": "Downloads Sorter",
  "description": "Files new downloads into folders by type.",
  "prompt": "A file arrived in Downloads. Move it into the matching folder under ~/Downloads/Sorted.",
  "tools": ["fs", "notification"],
  "trigger": {
    "source": "fileSystem",
    "filter": { "pathPatterns": ["~/Downloads/*"] }
  },
  "modelSelection": { "taskType": "mechanical" },
  "actionPolicy": "askFirst",
  "limits": { "cooldownSeconds": 30 },
  "workspaces": ["~/Downloads"]
}

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 (Paid and Trial)

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

They run in the background, and their 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
• Model fallback: when a model is rate limited or unusable, the sub-agent switches to another model (see Configuring Agents)
• The model limits of the agent that started it, which its own sub-agents inherit too

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: Memories are found by meaning, with a plain keyword search as a fallback
• Injection: When “Inject memories into system prompt” is on (Preferences > Memory; off by default), relevant memories are added to the system prompt at the start of each conversation turn, so a new conversation knows what you told Cogitae to remember. While it is off, the AI only finds memories when it searches for them
• Profile memories: With injection on, 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. Cleanup: Expired memories are removed, along with zombies (memories older than 30 days that have never been used)

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

The launcher hotkey is on from the start. Turn on the app toggle and inline text hotkeys in Preferences > Behavior. They 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. Turn on the inline text hotkey in Preferences > Behavior (once)
2. Select text in any application
3. Press Control+Command+Space (or the hotkey you set)
4. Cogitae captures the selection (requires Accessibility permission)
5. The launcher opens with the captured text shown as context
6. Type an instruction (“Summarize this”, “Translate to French”, etc.)
7. The AI receives the captured text + your instruction
8. Use “Copy & Paste Back” to paste the response, as shown, 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
• Set the timeout: how many seconds the server has to answer a request, tool calls included (30 by default, 0 for no limit). Raise it for servers whose tools take longer

Local (stdio) servers and the launcher: macOS does not let Cogitae run programs from folders such as /usr/local, /opt/homebrew or ~/.nvm, which is where npx, uvx and similar tools live. The first time you add or test such a server, Cogitae asks you to save a small launcher script, cogitae-mcp-launch, into ~/Library/Application Scripts/us.bitarts.cogitae/. Click Save without changing the name or folder. Local servers then run through it, using the same PATH as your shell. The server’s environment variables are passed privately and never appear in the process list.

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

A new server’s tools are turned on in the open conversation and in every new conversation, so you can use them right away. To leave one out of a conversation, untick it in the conversation’s Tools list (under “MCP: ”).

An MCP tool with the same name as one of Cogitae’s own tools (such as agent) is not offered to the AI, and the status bar shows a warning: calls by that name always run Cogitae’s tool, with its own confirmation. Rename the tool on the server to use it.

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 listens only on this Mac (localhost), speaks MCP over HTTP, and requires its token on every request (Authorization: Bearer <token>). Requests from web browsers (with an Origin header) or under another host name are refused, so a web page can’t reach it.

To connect Claude Code, click Copy Setup Command in Preferences > MCP Servers and run it in Terminal; it looks like:

claude mcp add --transport http --scope user cogitae http://localhost:52532 --header "Authorization: Bearer <token>"

--scope user makes Cogitae available to Claude Code in every folder. claude mcp list should then show cogitae as Connected.

New Token replaces the token; every client must then be given the new one.

MCP clients get the same checks as the AI: calls that change Cogitae, or reach your threshold, ask in a dialog naming the client; secrets in arguments are filled in, never shown; results are scrubbed of secrets. Native tools use the conversation’s workspace folders, never the home folder. Claude Code can then read your calendar, search Cogitae’s memories, and start Cogitae conversations on any of your models.

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)
• 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
• 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 runs in the macOS app sandbox and adds its own layers on top: folder grants, executable and SSH host approvals, confirmation of risky tool calls (see Tool Confirmation), secret handling, and checks on everything that can reach Cogitae from outside (MCP clients, links, the iPhone app). Grants are scoped so one conversation or agent can’t use another’s.

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). When the AI adds a workspace folder you haven’t granted yet, the same folder picker opens. The selected folder and all its subdirectories become accessible. The picker has a Read only checkbox: tools can then read but not change files there. A folder path the AI, a template or a shortcut sets counts as a workspace only if you granted it.

Scope: Each grant is owned by a context, and each context also sees the grants of the broader scopes above it:

A conversation checks conversation → all conversations → global; an agent checks agent → all agents → global. A conversation cannot see another conversation’s folders.

Links and protected folders: Paths are checked with symbolic links resolved, so a link inside a workspace can’t reach a folder outside it. Folders holding credentials (~/.ssh, ~/Library/Keychains, ~/.aws, ~/.gnupg, ~/Library/Cookies and similar) are reachable only if you grant that folder itself, never through a grant of your home folder.

Deleting: fs delete moves items to the Trash. Workspace roots and Cogitae’s data folder can’t be deleted or moved by tools.

Under the hood: Grants are macOS security-scoped bookmarks. At launch Cogitae refreshes stale bookmarks and follows folders that were moved or renamed. A grant that fails to resolve (for example on an unplugged drive) is kept, not deleted.

Cleanup: Deleting a conversation or agent, from anywhere, removes its grants and approvals. Grants of conversations deleted by older versions are removed at the next launch.

Global Workspaces

Global workspaces are folders granted at the Global scope: every conversation and agent can use them, and they are added to every conversation’s workspaces. 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.

Executable Permissions

The exec tool allows the AI to run programs. Every executable requires your approval before first use.

Approval flow:

1. The AI requests to run a command (e.g., git status)

2. Cogitae resolves the executable path (for git, the real git from the Command Line Tools or Xcode; see Developer tools below)

3. If not previously approved, an approval dialog shows the command (stored secrets appear by name) and any environment variables the AI sets, with scope options:

   • This conversation
   • All conversations
   • Global (all conversations & agents)

   An agent can’t show this dialog: approve its programs in advance under Preferences > Agents > the agent > Approved Executables, or add them to Global Executables in Preferences > Security.

4. An approval covers the program with any arguments and environment, not just the command shown, except for programs that run code given in their arguments (shells such as sh, bash and zsh, python3, node, ruby, perl, osascript, swift, env and the like): for those, Allow approves this exact command only. The dialog’s Allow any command with … option approves such a program for any arguments, which means any code. Approving a directory (e.g., /opt/homebrew/bin/) covers every executable in it.

Paths are compared after resolving .. and the links of their folders, so /opt/homebrew/bin/../../../anything is not covered by an approval of /opt/homebrew/bin/.

Approvals are bound to the program: Cogitae remembers which file it approved. A program signed by Apple, a Developer ID or the Mac App Store stays approved while it is signed by the same developer as the same program, so updates keep working. Any other program (a script, an unsigned or self-built binary, most Homebrew programs) is remembered by a fingerprint (SHA-256) of its contents: when it changes, for example when the AI rewrites ./build.sh or Homebrew upgrades it, Cogitae asks again and the dialog says the program changed since it was approved. Links are followed: an approval holds for the file a link leads to, a link that now leads somewhere else asks again, and the dialog shows both paths. An agent can’t ask, so it refuses a changed program and says why: run the program once from a chat, or remove it and add it again in Preferences. Approvals made with earlier versions of Cogitae are bound to the program as it is on their next run. Programs outside the folders Cogitae can read (such as /opt/homebrew/bin or a script in your home folder) are checked through the launcher script that runs them outside the sandbox; until the launcher is installed, Cogitae can’t check them, so it asks before each run and agents refuse them. Preferences > Security shows what each approval is bound to: who signed it, its file fingerprint, its exact commands, or any command.

Environment: Commands get your login shell’s environment, the approval’s stored variables, then the AI’s. The AI can’t set variables that change which code runs: PATH, HOME, DYLD_*, LD_*, GIT_SSH_COMMAND and other *_COMMAND hooks, GIT_CONFIG*, NODE_OPTIONS, PYTHONPATH and similar. Set those as stored variables of the approval if a program needs them.

Working directory: A command runs in one of the conversation’s workspace folders (the first by default); a working directory outside them is refused.

Timeouts and cancel: When a command times out or you stop the query, Cogitae stops it and every process it started.

Developer tools: /usr/bin/git, /usr/bin/python3 and the other developer tools in /usr/bin are stubs that can’t run inside the app’s sandbox. Cogitae runs the real tool from Xcode or the Command Line Tools instead, and which reports that path. An approval of either path covers both, so /usr/bin/git in an agent’s Approved Executables lets it run git. /usr/bin/which is approved globally when Cogitae is first installed.

Programs outside the system’s folders: macOS’s app sandbox doesn’t let Cogitae start programs from Homebrew (/opt/homebrew) or ones you built yourself, even with access to their folder. When the sandbox refuses one, Cogitae asks separately whether it may run outside the sandbox, where it has your full access to files and the network; the answer is remembered with the program’s approval. It then runs through the same launcher script local MCP servers use. The first time, Cogitae asks you to save the launcher in its Application Scripts folder. Agents can’t ask either question: run the program once from a chat first. Such a command’s stdin is empty, and it is stopped after its timeout or when you cancel.

Inheritance chain: conversation → all conversations → global; agent → all agents → global.

Headless agents can only use executables approved at a scope visible to them; others fail.

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.

SSH

The ssh tool uses your SSH keys. Each host needs your approval, like an executable: the first call to a host asks, for this conversation or agent, all of them, or everywhere (stored as ssh:<host> in the executable approvals). Agents use only approved hosts. Writing files and running commands on the host are moderate-risk operations. A host key is trusted the first time Cogitae connects (accept-new), and a host name starting with - is refused.

Secrets

Secrets (API keys, database passwords, tokens) are stored in the macOS Keychain on this Mac only (never synced) and managed through Preferences > Security. Their names, descriptions, allowed hosts and allowed tools are kept in a plain file in Cogitae’s Application Support folder.

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}}. Every conversation and agent can use every secret.

Where a secret may go: A web request that would send a secret (in its URL, headers or body) to a host not allowed for that secret asks first, naming the secret and the host; Always Allow This Host remembers it. Any other tool that would get a secret (a command run with exec, ssh, an MCP server’s tool, a plugin, or a Cogitae tool such as file or memory) asks first too, naming the secret, the tool, its action and any hosts in the call (the MCP server for an MCP tool); Always Allow for This Tool remembers it for that secret only. Agents and other sessions with no one to ask are refused until the host or tool is allowed (allow it once from a chat). Allowing all similar calls never covers a secret, and changing a secret’s value forgets its hosts and tools.

Redaction: Every stored secret’s value, and its base64 and URL encoded forms, are replaced by [REDACTED:name] in tool output before the AI sees it, including secrets not used since launch. Values shorter than four characters, and text inside images, are not redacted.

Sensitive content detection: When a tool result contains a value that looks like a secret (KEY=VALUE, JSON or YAML keys like apiKey or password, Authorization: headers) but is not already in the secrets store, a dialog appears:

• Add to Secrets — Stores the value in the Keychain
• Allow Access — The AI may see this value in this conversation (until Cogitae quits)
• Redact — Hides the value from the AI immediately

Headless agents redact such values without asking.

Changes: Setting or deleting a secret changes Cogitae, so it always asks; agents can’t do it.

Permission Inheritance

Conversations → Tools: A conversation’s workspace folders, executable approvals and SSH hosts apply to every tool call in it.

Conversations → Sub-agents: Sub-agents started from a conversation (Caesar, Sherlock, Patton and the other specialists) run in the conversation’s scope with its workspaces, so programs and SSH hosts the conversation approved run for them without asking, and anything new asks in the conversation. They get only tools the parent can use (its enabled tools, within an agent parent’s allowed list and without its excluded tools), and their dialogs appear in the parent chat. A sub-agent can’t revoke its parent’s grants.

Event-driven agents run headless: they can’t ask for new folders, executables or hosts, can’t change Cogitae, and rely on grants and approvals at a scope visible to them (agent, all agents, global). Their sub-agents inherit that, including a Notify Only agent’s read-only limit and the agent’s model policy.

Outside callers:

Network Security

Web requests (via the web tool) and markdown images only use http or https, and are refused when their host resolves to a private or internal address: localhost, LAN ranges, link-local, carrier-grade NAT (100.64/10), benchmarking (198.18/15), reserved and multicast ranges, and IPv4 addresses hidden in IPv6 forms. A host that doesn’t resolve is refused. Every redirect is checked, and so is the address the request actually connected to (a host that changes its DNS answer between the check and the connection is caught; its response is discarded).

Remote images: An image in a reply sends a request to its host, and its address can carry text from the conversation. By default (Preferences > Markdown > Remote images: Ask per host) a remote image shows as a placeholder naming its host; click it to load it once or always for that host. You can also choose Always load or Never load, and forget the allowed hosts.

Preferences

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

Sections

Appearance

Window appearance settings update in real time:

• App mode: Switch between HUD mode (floating, status bar) and App mode (standard window, Dock icon). Takes effect on next launch
• Notifications: Send system notifications when hibernating

Behavior

• Global hotkeys: Three independent hotkey recorders — app toggle, launcher, inline text
• Voice input: Use server-side speech recognition instead of on-device recognition, which is faster and works offline
• Network sleep: Keep network connections alive during system sleep for iOS companion access
• 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
• Remote images: Ask per host (default), Always load or Never load; Forget Allowed Hosts clears the hosts allowed so far
• Clear markdown cache: Purge the rendered markdown cache

AI

• Token usage: Table showing input/output tokens and cost per provider, with a clear button. It covers everything Cogitae is billed for: replies, summaries, embeddings, image generation and Gemini context caches (creation and storage). A cost marked * leaves out requests that could not be priced; the note under the table says how many.
• Accounts: One row per API key or local server — add, edit, or delete (the trash button in the account form, right-click a row, or swipe left on it). A row in red has no API key
• Default Model: The model new conversations start on. It is chosen when you add your first account; each conversation can pick its own model and keeps it
• Summarization AI: Model used for auto-summarization. When you add your first account it is set to the cheapest enabled model
• Default iOS AI: Model used by the iOS companion app. Default Model follows the Default Model above
• Embedding AI: Embedding model used for memory and plugin embeddings, grouped by account (only providers with an embedding endpoint). When you add your first OpenAI, Google or Mistral account it is set to that account’s embedding model until you pick one. Changing it re-embeds existing memories and plugin collections
• Show reasoning progress (on by default): While a reply is being prepared, show what the model is doing — connecting, waiting, the latest line of its reasoning summary — on the status bar and in the iOS app. Claude, OpenAI and Grok models are asked for a summary of their reasoning; this does not change what the request costs
• 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 — has the AI investigate a problem from Cogitae’s logs before drawing conclusions, and tells you to turn on debug logging if there are none
  • 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

Account Editor

When adding or editing an account in Preferences > AI:

• Provider: Provider type (Anthropic, OpenAI, Google, etc.)
• Host: API base URL (filled in for cloud providers)
• API Key: Stored in macOS Keychain (secure text field). Each account has its own key
• Name: Display name for the account
• Use Flex processing for agents (OpenAI, Gemini): agents’ requests use the half-price Flex tier
• System Instructions: Default system prompt, used when a new conversation has no instruction prompt
• Re-detect: Probes the account’s API endpoints again and saves. Saving runs the same check

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

Models

Preferences > Models lists every model of your accounts, grouped by account. Any of them can be picked in a conversation; the list decides what automatic choices use.

• Agents: Check a model to let agents, sub-agents and fallbacks pick it. They pick by scores and price, so an unscored model is used only as a last resort or by hand. A new cloud account starts with its scored models checked; OpenRouter, llama.cpp, MLX and Custom models start unchecked
• Intel. / Code / $/M / Context: The model’s intelligence and coding indices, blended price per million tokens and context window, from the model catalog
• Capabilities / Status: What the model can do (tools, vision, reasoning, …). For local and Custom models, how it is scored
• Enabled / All and the search field narrow the list by account, model name or alias
• Settings (slider button): the model’s defaults for new conversations (temperature, max tokens, reasoning effort, stop sequences, …; only those the model takes), and for llama.cpp, MLX and Custom models your own scores. Reset removes them

Local models. A llama.cpp server reports a fingerprint for each model, which stays the same whatever the file is called. Cogitae asks the model catalog about it; when the catalog knows the weights, the model is linked to them, takes their benchmark scores at no cost, uses the context the server runs, and is checked for agents. Scores cover 4-bit quantizations and up: a smaller file is linked but unscored. A model with no scores (no match, too low a quantization, or an MLX or Custom model, which report no fingerprint) gets a one-time notice; you can set scores for it in its settings, and your scores always win over the catalog’s. An unmatched model is checked again, at most once a day, when you use it, and you are told when scores become available.

New models the catalog adds are not checked by themselves. The new-model notice in the notification feed (for example “New Anthropic model available”) has an Enable for Agents button that checks them on every account of that provider.

Usage Report

Click the tokens and cost at the right of the status bar to add the usage report to the conversation. It shows a detailed cost and token breakdown:

• Per-message input/output token counts
• Session totals aggregated by provider
• Estimated cost with cache savings percentage. Each reply is priced for the model that wrote it, when it finished. Grok and OpenRouter replies show what the provider actually billed; DeepSeek replies outside its peak hours (01:00–04:00 and 06:00–10:00 UTC on weekdays) are priced at its half-price off-peak rate; server web searches add $0.01 each (Claude, OpenAI) or $0.014 per search query (Gemini).
• Cache performance over the last 30 days, across all conversations: hit rate, requests that used the cache, and total cost of everything billed in that time. Writing the cache costs more than plain input (1.25x on Claude and OpenAI), so a first reply can cost more than it would without caching; later replies read it cheaply.
• Agent usage breakdown (if agents were used)

Token usage is shown for every cloud provider and llama.cpp. MLX and custom servers do not report it.

MCP Servers

• Embedded MCP server: Toggle to enable the built-in MCP server, with configurable TCP port (0 = auto-assign) and status display. Copy Setup Command copies the claude mcp add command with the server’s token, Copy Token copies the token for other clients, and New Token replaces it (clients then need the new one)
• 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. How it works depends on the model: Claude models (from Anthropic) are sent every enabled tool unloaded and search for the ones a request needs, which keeps the conversation in the prompt cache. Other cloud providers (OpenAI, Gemini, Grok, DeepSeek, Mistral, OpenRouter, Claude through OpenRouter included) cache the prompt, so they are sent every tool: enabling tools one at a time would change the prompt and cost more. The optimizer itself is used for llama.cpp, MLX and custom servers, where it keeps tool definitions out of the model’s context window
• Ask before: Destructive operations only (default) or Anything that changes something: which tool calls ask first. Operations that change Cogitae itself always ask (see Tool Confirmation)
• 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
• Restart: An update to a plugin that is already running takes effect only after Cogitae restarts, since the running version cannot be unloaded. Until then a banner above the list names every plugin waiting for a restart, each row shows the version that will load and the one still running, and the banner’s Restart button quits and reopens Cogitae. Several updates can wait for one restart.

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

Security

• Secrets: Keychain-stored secrets for tools that need credentials. Each row shows the hosts web requests may send the secret to (“Sent to”) and the other tools that may receive it (“Tools”); changing the value forgets them. See Secrets
• Global Executables: Executables every conversation and agent may run. See Executable Permissions
• Global Workspaces: Folders every conversation and agent may use. See Global Workspaces

License

• 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, or Paid
• Status: Activation status (Active, Limited, Not activated, or Activation released when another Mac has taken this one’s slot)
• 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, headed by the number of Mac activation slots in use. iPhones and iPads are listed but use no slot
• Replacing a Mac: Activating on a new Mac while the license is at its limit offers a list of the Macs holding slots; choosing one deactivates it and activates this Mac in a single step

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 reaches your Mac two ways:

• LAN (Bonjour): The app finds Macs on the same network. Pair each Mac once: in the app’s Settings > Macs, tap Pair next to the Mac. The Mac and the iPhone both show a six-digit code; if they match, tap Codes Match on the iPhone and Pair on the Mac. After that every message on the network is encrypted and only paired devices are accepted.
• WAN (Relay): Through the Cogitae relay server. Enable in Preferences > Remote Access on the Mac. Only paired iPhones can use your Mac through the relay: every message is encrypted end to end and proves which paired iPhone sent it, so neither the relay nor anyone else with your license can send your Mac a prompt or read your replies. An iPhone paired on the LAN can use the relay straight away. To pair one away from the Mac’s network, click Pair iPhone over Relay… in the Mac’s Preferences > Remote Access, then tap Pair over the Internet in the app’s Settings > Macs within five minutes, and compare the codes the same way. The Mac answers pairing requests over the relay only while that sheet is open.

The Mac’s Preferences > Remote Access lists the Paired iPhones: name, key fingerprint, when each was last seen on the network and through the relay, a Relay checkbox (turn it off to keep that iPhone to the local network) and Remove, which unpairs it on both and stops its notifications. Allow paired iPhones on this network turns the LAN channel off. In the app, swipe a paired Mac to Forget it.

To check you are talking to your own Mac, compare the Device Key fingerprint in the Mac’s Preferences > Remote Access with the one the app shows under the Mac. The app uses the key you checked when pairing, on the network and through the relay, never one a server reports.

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.

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, grouped by month as on the Mac, with search filtering, create new ones, send messages, view responses. The list you saw last shows at once and updates when the Mac answers
• Pull to refresh: Pull a conversation down to bring in messages added on the Mac since, including in conversations you started on the iPhone
• Branches: Work as on the Mac. A reply with several branches has a branch menu under it: pick a branch to switch to it (a Mac window showing the conversation follows). Tap the branch button under a reply to start a new branch there: the messages after it are hidden and your next message starts the branch (the button becomes Cancel). A message that starts a branch shows the branch’s name; touch and hold it and choose Rename Branch to rename it. What you send continues the branch the iPhone shows, even if the Mac has switched to another since. Needs Cogitae 1.1.15 or later on the Mac
• Agent dashboard: View, start, stop, and run agents on any connected Mac, and read each agent’s last result (tap an agent for all of it)
• Agent results: When an agent set to Act and Notify or Notify Only finishes, its result arrives on your iPhone as a notification, even when the app is closed and the phone is away from your Mac (this needs the relay: Preferences > Remote Access)
• Agent questions: Answer agent ask_user questions remotely
• Progress while you wait: The waiting bubble shows what your Mac is doing with the question — connecting to the AI provider, waiting for a reply, the latest line of the model’s reasoning, or the tool it is running — over both LAN and relay
• Push notifications: Silent push for background message delivery
• Multi-Mac: Tab-per-Mac interface for managing multiple Macs
• Version: Settings > About shows the app’s version and build

License Sync

The iOS app gets your license from your Mac through iCloud, so you don’t enter the key twice.

Finder Integration

Cogitae adds a 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. A shortcut runs when you run it, or when an automation you set up fires, so intents that ask the AI run headless (like an agent): tools that change Cogitae are refused, file operations stay in the workspace folders you granted, and Open Workspace works only with a folder Cogitae already has access to.

AI Intents

Actions that take a model list each model with its account below it. A shortcut made before accounts replaced providers needs its model chosen again.

Data Intents

UI Intents

Focus Filters

Cogitae supports macOS Focus Filters, allowing you to override the default model, 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.

Any app, and any web page (after the browser asks), can open a cogitae:// link, so only actions that change nothing and reveal nothing private run without asking:

Every other call (for example cogitae://conversation/list or cogitae://memory/store?key=foo&content=bar) asks first in a dialog naming the app that opened the link, and runs in the active conversation’s scope with the same checks as the AI.

x-callback-url Support

Links from the table above can include x-success and/or x-error to receive results via callback URLs:

cogitae://app/info?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>

Other calls never answer through callbacks; their 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

Query Progress

While a reply is being prepared, the text next to the dot shows its progress: “Connecting to …”, “Waiting for response…”, then the latest line of the model’s reasoning summary for Claude, OpenAI and Grok models. A line too long for the strip is cut short; hover over it to read all of it. Turn this off in Preferences > AI > Show reasoning progress.

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. The totals include sub-agents, conversation summaries, and the finished steps of a reply that failed or was stopped. Click it to show the usage report.

Notification Badge

Red badge on the right counts unread warnings, errors, agent results and other notices worth a look (hidden when zero, caps at “99+”). Routine progress notices, like the ones each query posts, are listed in the feed but don’t raise the badge.

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 or buttons to expand it (up to 3 lines of detail text). Some notifications offer buttons, such as Enable for Agents on a new-model notice; a button works once, then the notification’s buttons are removed. 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:

Your conversations, files, memories and API keys stay on your Mac. Only licensing data, such as your license key, a hash of your email address and your activated devices, is stored on BitArts servers.

License System

Cogitae is unlocked with a license key. There are no user accounts or passwords.

License Types

The Macs column counts Macs only — iPhone and iPad activations are unlimited on every tier and do not count against the limit.

Every license can use the iOS app over your local network. Reaching your Mac from the iOS app away from home uses the relay. Outside the periods above, any license can subscribe to it.

License Key Format

CGTA-XXXX-XXXX-XXXX-XXXX

Troubleshooting

Common problems, and how to turn on logs the AI can use to investigate, are on the Troubleshooting page.

Last updated September 30, 2026