Cogitae Troubleshooting — Fixing Common Problems
Most problems have a quick fix below. If yours doesn’t, turn on logging and ask the AI to investigate, or contact support.
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 Paid license or an active trial
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.
| Agent | Base Tools |
|---|---|
| Aristotle | read, search, memory, ask_user, conversation, caesar, web, socrates, tool_optimizer |
| Newton | file, search, memory, ask_user, conversation, caesar, web, socrates, academic_search, tool_optimizer |
| Da Vinci | file, search, memory, ask_user, conversation, caesar, web, socrates, newton, tool_optimizer |
| Patton | file, search, memory, ask_user, conversation, caesar, web, socrates |
| Sherlock | file, fs, search, exec, memory, internal_memory, ask_user, conversation, caesar, socrates, tool_optimizer |
| Socrates | (none — intentionally toolless auditor) |
| Caesar | Whatever tools the AI specifies per sub-agent |
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 ask the AI to give the agent extra tools when it starts one.
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
- The global hotkeys themselves 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. Any license can subscribe to the relay; a trial includes it while it lasts, and a Paid license includes the first 30 days
- Check relay status in Preferences > Remote Access
- Away from home, the iOS app’s “No Macs Found” screen says what the relay is doing: still connecting, unreachable (with the reason), or not accepting the license. The same status is under Relay in the app’s Settings
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 runs in Terminal
- If a stdio server says it needs the launcher, edit it and click “Test Connection”, then save the launcher when asked
- Click “Test Connection” in the server editor
- Check that the server is running and accessible
Sandboxing problems
Cogitae runs in the macOS App Sandbox. This affects a few things:
- A server on your local network seems offline: plain
http://connections to a hostname such ashttp://myserver:9111can fail with “The Internet connection appears to be offline”, even though the network is fine. Use the server’s IP address instead, such ashttp://192.168.1.2:9111. This most often affects MCP servers running on another machine. - Home folder paths: Cogitae’s own folder,
~/.cogitae/, is inside its sandbox. Any other~path you give a tool means your real home folder, so it matches the folders you have granted. - Plugins blocked by Gatekeeper: a downloaded plugin can keep the quarantine flag that makes macOS block it. Preferences > Plugins shows each plugin’s status.
Debugging
Cogitae can keep logs of what it did, and the AI can read them with the debugger tool to work out what went wrong. Logs are kept on your Mac and deleted after 7 days.
- Agent logging is on by default. It records what agents do: tool calls, plan steps, memory use and errors. Turn it off under “Agent Logging” in Preferences > Agents, which also deletes the agent log.
- Debug logging is off by default, because it uses disk space. It records every tool call, every request to an AI provider (model, tokens, time and errors), and groups related steps into sessions. Turn it on with Enable self-debugging database logging under “Debug Info” in Preferences > Behavior. Turning it off deletes these logs.
Both settings take effect immediately.
To investigate a problem, enable the debugger tool in the conversation’s tool selector and ask the AI what happened, for example “Why did my file monitor agent fail this morning?” The Cogitae Debugging instruction prompt in Preferences > AI sets the AI up for this.