Docs

Troubleshooting

Solutions to common issues, error messages, and optimization tips for Agentastic. If you can't find your issue here, send us feedback or email support@agentastic.com.

Quick Fixes

Before diving into specific issues, try these general solutions:

  1. Restart Agentastic - Quit completely and relaunch
  2. Check Permissions - System Settings → Privacy & Security
  3. Update to Latest - Check for updates in Settings
  4. Clear Cache - Settings → Advanced → Clear Cache
  5. Reset Settings - Hold ⌥ while launching

Installation Issues

"Agentastic can't be opened because it is from an unidentified developer"

Solution:

  1. Right-click the Agentastic app in Applications
  2. Select "Open" from the context menu
  3. Click "Open" in the dialog
  4. This only needs to be done once

App Won't Launch

Check these:

  1. macOS version 12.0 or later
  2. At least 2GB free RAM
  3. No conflicting apps running
  4. Check Activity Monitor for stuck processes

Fix:

# Kill any stuck processes
pkill -f agentastic

# Clear launch services
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user

# Try launching again
open -a Agentastic

Menu Bar Icon Missing

Solutions:

  1. Check if hidden in menu bar (drag to reveal)
  2. Restart Agentastic
  3. Reset menu bar: 
    defaults delete com.agentastic.app NSStatusItem
  4. Check Bartender or similar apps

Permission Issues

Accessibility Permission Not Working

Symptoms:

  • Expansions don't trigger
  • Keyboard shortcuts don't work
  • "Accessibility access required" error

Fix:

  1. System Settings → Privacy & Security → Accessibility
  2. Remove Agentastic if present (click -)
  3. Re-add Agentastic (click +)
  4. Ensure toggle is ON
  5. Restart your Mac

Screen Recording Permission

Symptoms:

  • Vision mode not working
  • /screen commands fail
  • Black screenshots

Fix:

  1. System Settings → Privacy & Security → Screen Recording
  2. Toggle Agentastic ON
  3. Quit and restart Agentastic
  4. Test with /screen What do you see?

Note: Vision mode and screen capture features require macOS 14.0 (Sonoma) or later. On macOS 12-13, these features will be disabled.

File Access Issues

Symptoms:

  • /files commands fail
  • "Permission denied" errors
  • Can't read/write files

Fix:

  1. System Settings → Privacy & Security → Files and Folders
  2. Grant access to needed folders
  3. Or use Full Disk Access (not recommended)

Expansion Problems

Expansions Not Working

Check:

  1. Expansion is enabled in settings
  2. Correct trigger typed
  3. Followed by space (or configured delimiter)
  4. Not in excluded app

Debug:

# Check if expansions are loading
agentastic debug expansions

# Test specific expansion
agentastic test "your_trigger"

Unwanted Expansions

Solutions:

  1. Make trigger more unique
  2. Enable word boundaries
  3. Add app to exclusion list
  4. Use case sensitivity

Example fix:

expansions:
  problematic_trigger:
    old: "im"
    new: ";im"  # Add prefix
    case_sensitive: true
    word_boundaries: true

Expansion in Wrong App

Fix app-specific settings:

apps:
  Terminal:
    expansions_enabled: false
  
  Xcode:
    trigger_key: "tab"
    
  Mail:
    auto_capitalize: true

Pattern Matching Issues with Arrow Keys

Symptoms:

  • Patterns like [] or [text] don't trigger after using arrow keys
  • Expansions fail when editing text mid-word
  • Matching resets when navigating

Solution - Enable Cursor-Aware Matching:

# In your config file
enable_cursor_aware_matching: true

What this fixes:

  • Maintains pattern state through arrow key navigation
  • Allows editing within patterns without breaking detection
  • Preserves matching buffer when moving cursor

Debug cursor-aware issues:

# Check if feature is enabled
agentastic config show | grep cursor_aware

# View matching behavior in logs
agentastic log | grep cursor-aware

# Test with specific pattern
agentastic test "[hello]" --cursor-aware

Note: This is an experimental feature. Disable if experiencing unexpected matching behavior.

AI Features Issues

Slow AI Responses

Optimize:

  1. Use appropriate model:

    • /model:fast for simple tasks
    • /model:smart for general use
    • /model:genius only when needed

  2. Check internet speed:

    # Test connection
ping -c 5 api.agentastic.com

  3. Clear AI cache:

    • Settings → Advanced → Clear AI Cache

AI Not Working

Troubleshoot:

  1. Check internet connection
  2. Verify API status: status.agentastic.com
  3. Test with simple prompt: @ai Hello
  4. Check firewall/proxy settings

Vision Mode Issues

Common problems:

  1. Black screen: Grant screen recording permission
  2. Wrong monitor: Use /screen:1 or /screen:2
  3. Partial capture: Check display scaling
  4. Performance: Disable when not needed

Launcher Issues

Launcher Won't Open

Try:

  1. Check keyboard shortcut conflicts
  2. Reset launcher shortcut: 
    defaults write com.agentastic.app launcherShortcut "cmd+space"
  3. Check if another app is intercepting

Launcher Appears Behind Windows

Fix:

defaults write com.agentastic.app launcherLevel "floating"

Options: normal, floating, screen-saver

Launcher Position Issues

Reset position:

defaults delete com.agentastic.app launcherPosition

Or drag to preferred location and it will remember.

Conversation Loading Issues

Bookmarked conversation doesn't load:

  1. Verify conversation was bookmarked successfully (check Settings → Bookmarks)
  2. Ensure conversation file isn't corrupted
  3. Try loading a different conversation to test the feature
  4. Restart both Settings app and launcher

Conversation appears empty after loading:

  1. Check that the conversation has actual message content
  2. Wait a moment for the conversation to fully load
  3. Try closing and reopening the launcher
  4. Clear conversation cache in Settings

"Load" button doesn't work:

  1. Ensure launcher is not already running with a conversation
  2. Check for permission issues
  3. Try using keyboard shortcut ⌘+S to bookmark, then load again
  4. Restart the Settings app

Text Selection Popup Issues

Multiple Popups Appearing

Symptoms:

  • Two or more purple popup buttons visible simultaneously
  • New popup appears before old one disappears
  • Popups overlapping or cluttering the screen

Solution: This issue has been fixed in the latest version. The system now ensures only one popup appears at a time. If you're still experiencing this:

  1. Update to the latest version of Agentastic
  2. Ensure enable_text_selection_timer_monitoring is set to false (default) in your config
  3. Restart the launcher

Text Selection Popup Not Appearing

Common causes and fixes:

1. Feature is disabled:

  • Open Settings → General settings
  • Enable "Text Selection Popup" toggle
  • Or add to config: show_agentastic_shortcut: true

2. Mouse selection not detected:

  • Some applications may not trigger mouse selection events properly
  • As a last resort, enable timer monitoring in config: 
    enable_text_selection_timer_monitoring: true  # Use with caution
  • Note: Timer monitoring may cause duplicate popups

3. Accessibility permissions:

  • System Settings → Privacy & Security → Accessibility
  • Ensure Agentastic is enabled
  • Remove and re-add if already present

Popup Appears in Wrong Position

Fix positioning issues:

  1. Check multi-monitor setup and display arrangement
  2. Verify display scaling settings
  3. Reset popup position: 
    defaults delete com.agentastic.app popupPosition

Popup Disappears Too Quickly

Adjust auto-hide timer: The popup auto-hides after 3 seconds by default. This is not currently configurable but will remain visible if you hover over it.

Memory System Issues

Memory Not Saving

Check:

  1. Memory enabled in settings
  2. Channel configured correctly
  3. Sufficient disk space
  4. Write permissions

Debug:

# Check memory status
agentastic memory status

# Test memory write
agentastic memory test

Wrong Channel Assignment

Fix routing:

channels:
  work:
    keywords: ["project", "meeting", "deadline"]
    priority: 10  # Higher priority
    
  personal:
    keywords: ["home", "family"]
    priority: 5

Performance Optimization

High CPU Usage

Reduce load:

  1. Limit active expansions (<500 recommended)
  2. Disable unused features
  3. Reduce AI cache size
  4. Lower thread pool size

Settings:

performance:
  max_expansions: 500
  ai_cache_size: "50MB"
  thread_pool: 2
  idle_timeout: 300

High Memory Usage

Solutions:

  1. Archive old memory channels
  2. Clear expansion cache
  3. Reduce history size
  4. Restart periodically

Slow Typing

Fix input lag:

  1. Disable complex expansions
  2. Reduce middleware pipeline
  3. Check for app conflicts
  4. Update to latest version

Error Messages

"API Rate Limit Exceeded"

Meaning: Too many AI requests Fix:

  • Wait 60 seconds
  • Use /model:fast more
  • Enable smart caching

"Expansion Loop Detected"

Meaning: Expansion triggers itself Fix:

  • Change trigger
  • Disable recursive expansion
  • Add loop protection

"Memory Channel Full"

Meaning: Channel storage limit reached Fix:

  • Archive old memories
  • Increase retention limit

"Cannot modify protected content" Error

Meaning: The AI attempted to modify content within <permanent_instruction> tags

What happened: The AI tried to edit or delete a section of memory that you've protected with permanent instruction tags.

What to do:

  1. This is expected behavior - the protection is working correctly
  2. The protected content has been preserved unchanged
  3. The AI will learn from this error and avoid modifying that section in future
  4. If you want the AI to update this content, you must manually edit the memory file and remove or update the <permanent_instruction> tags

Example error message:

Cannot modify or remove content within <permanent_instruction> tags.

The following protected content is missing or modified:

<permanent_instruction>
Always be encouraging when discussing fitness...
</permanent_instruction>

Please make edits that preserve all permanent instructions.

How to fix:

  1. Open the memory file directly in a text editor
  2. Remove the <permanent_instruction> tags if you want the AI to edit that content
  3. Or manually update the content yourself while keeping the tags
  4. Save the file

Preventing this error:

  • Only use permanent instruction tags for truly critical, unchanging directives
  • Place frequently-updated information outside protected tags
  • Review protected content occasionally to ensure it's still relevant

"Cannot modify user.md" Error

Meaning: The AI attempted to edit the user.md file

What happened: The user.md file is completely read-only for the AI - it cannot be modified under any circumstances.

What to do:

  1. This is expected behavior - user.md is protected for your safety
  2. If you want to update user.md, edit it manually
  3. File location: ~/Library/Application Support/agentastic/memory/user.md (macOS)

Why user.md is protected:

  • Contains your core preferences and instructions
  • Should only be modified intentionally by you
  • Prevents accidental overwrites of critical information
  • Create new channel

"Permission Denied: [Feature]"

Meaning: Missing system permission Fix: Grant permission in System Settings

Advanced Debugging

Enable Debug Mode

# Start with debug logging
agentastic --debug

# Or set in config
echo "debug: true" >> ~/.config/agentastic/config.yaml

View Logs

# Live log viewing
agentastic log -f

# Filter by component
agentastic log --filter="expansion"

# Export logs
agentastic log export > debug.log

Performance Profiling

# Profile expansions
agentastic profile expansions

# Profile AI requests
agentastic profile ai

# System resource usage
agentastic stats

Reset and Recovery

Reset Specific Components

# Reset expansions
agentastic reset expansions

# Reset AI cache
agentastic reset ai-cache

# Reset memory
agentastic reset memory

# Reset everything
agentastic reset all

Backup and Restore

# Backup all data
agentastic backup create

# Restore from backup
agentastic backup restore "backup-2024-01-15.zip"

# List backups
agentastic backup list

Getting Help

Before Contacting Support

  1. Check this guide
  2. Update to the latest version
  3. Collect debug logs

Information to Provide

  • Agentastic version
  • macOS version
  • Error messages
  • Steps to reproduce
  • Debug logs

Contact Options

Prevention Tips

Regular Maintenance

  1. Weekly: Clear cache, review expansions
  2. Monthly: Archive memories, check permissions
  3. Quarterly: Review settings, update

Best Practices

  1. Keep expansions under 1000
  2. Use appropriate AI models
  3. Regular backups
  4. Monitor resource usage
  5. Update promptly

Remember: Most issues have simple solutions. Start with quick fixes before diving into advanced troubleshooting!