Skip to main content
This guide covers common problems and their solutions. If your issue isn’t listed here, check the Pentagon GitHub repository for open issues.

​
Installation Issues

​
Gatekeeper Warning

macOS may show “Pentagon can’t be opened because it is from an unidentified developer.” Fix: Right-click (or Control-click) the app and select Open. Click Open in the confirmation dialog. You only need to do this once.

​
”App Is Damaged” Error

If macOS says Pentagon is damaged and can’t be opened: 
xattr -cr /Applications/Pentagon.app
This removes the quarantine attribute macOS applies to downloaded apps. Then open Pentagon normally.

​
Permissions Not Granted on First Launch

If you clicked “Don’t Allow” when Pentagon requested file access:
  1. Open System Settings > Privacy & Security
  2. Click Files and Folders (or Full Disk Access)
  3. Find Pentagon in the list
  4. Toggle on the required access
See Permissions for the full list of directories Pentagon needs.

​
Claude Code Issues

​
Claude Code Not Found

Pentagon can’t locate the claude binary. Symptoms: Agents fail to start with a “command not found” error. Fix:
  1. Verify Claude Code is installed: 
    claude --version
  2. If not installed, install it following the Claude Code documentation
  3. Make sure claude is on your PATH — Pentagon searches standard paths (/usr/local/bin, /opt/homebrew/bin, ~/.local/bin)

​
API Key Issues

Agents start but fail with authentication errors. Fix:
  1. Verify your API key is set: 
    echo $ANTHROPIC_API_KEY
  2. If not set, add it to your shell profile (~/.zshrc or ~/.bashrc): 
    export ANTHROPIC_API_KEY="sk-ant-..."
  3. Restart Pentagon after updating your shell profile

​
Agent Issues

​
Agent Won’t Start

The agent desk appears but the session never initializes. Check:
  1. Verify Claude Code works standalone: 
    claude --version
  2. Check that the project directory exists and is accessible
  3. Ensure macOS permissions are granted (see Permissions)
  4. Try spawning an agent in a different directory

​
Agent Stuck in Active State

The agent shows a yellow “Active” ring but nothing is happening. Cause: Pentagon performs a stale sweep — if an agent reports active status for more than 60 seconds without any tool calls or output, it may be stale. Fix:
  1. Check the terminal tab for any output or errors
  2. Wait for the stale sweep (60 seconds) to reset the status
  3. If still stuck, respawn the agent from its context menu (right-click the desk)

​
Agent Not Responding

The agent is in “Ready” state but ignores input. Fix:
  1. Click the agent desk to make sure it’s selected
  2. Press Cmd + L to focus the terminal input
  3. Type your message and press Enter
  4. If unresponsive, respawn the agent (right-click > Respawn)
Respawning kills the current process and starts a fresh Claude Code session. The agent’s soul, tasks, and memory persist.

​
Canvas Issues

​
Agent Desks Not Appearing

You spawned an agent but nothing shows on the canvas. Check:
  1. Look in the sidebar agent list — if the agent appears there, it exists but may be off-screen
  2. Use the minimap (bottom-right) to locate the desk
  3. Click the reset view button (scope icon) to reset zoom and position
  4. Check if the canvas panel is hidden — press Cmd + E to toggle it

​
Canvas Performance

If the canvas feels slow:
  1. Reduce the number of active agents — terminate or set idle agents to dormant
  2. Check Activity Monitor for CPU usage
  3. Restart Pentagon

​
File Permission Issues

​
Agents Can’t Read or Write Files

Fix:
  1. Grant Full Disk Access to Pentagon:
    • System Settings > Privacy & Security > Full Disk Access
    • Toggle Pentagon on
  2. Verify ~/.pentagon/ exists: 
    ls -la ~/.pentagon/
  3. If the directory is missing, Pentagon creates it on first launch — try restarting the app

​
History or Settings Not Saving

If configurations reset when you relaunch:
  1. Check that ~/.pentagon/ is writable: 
    touch ~/.pentagon/test && rm ~/.pentagon/test
  2. If permission denied, fix ownership: 
    sudo chown -R $(whoami) ~/.pentagon/

​
Data Recovery

​
Restoring from Backup

Pentagon stores all data in ~/.pentagon/. If you use Time Machine or another backup tool:
  1. Open Time Machine (or your backup tool)
  2. Navigate to ~/.pentagon/
  3. Restore the directory to recover agents, settings, and history

​
Full Reset

If Pentagon is in a broken state and nothing else works: 
rm -rf ~/.pentagon/
This deletes all agent data, settings, and history. Pentagon will recreate the directory on next launch with default settings.
After resetting, relaunch Pentagon. You’ll need to reconfigure your preferences and spawn new agents.

​
Getting Help

If your issue persists:
  1. Check the terminal tab for error messages — they often explain what went wrong
  2. Look at Console.app for Pentagon-specific log entries
  3. File an issue on the Pentagon GitHub repository with steps to reproduce

​
Next Steps