Common Issues

Solutions to frequently encountered problems

Git Not Working

Symptoms

  • Git commands fail in terminal
  • Source control features don't work
  • "git not found" errors

Solution

Agentastic is distributed without sandbox restrictions for full Git access. These Developer ID builds are not Mac App Store compatible and should only be distributed with clear security justification and user disclosure. Ensure Git is installed:

# Check if Git is installed
git --version

# Install via Xcode Command Line Tools
xcode-select --install

# Or via Homebrew
brew install git

Terminal Not Opening

Symptoms

  • Terminal tab appears blank
  • No shell prompt

Solution

  1. Check your shell path in Settings > Terminal
  2. Verify the shell exists: 
    which zsh    # or bash, fish, etc.
  3. Try switching terminal backends in Settings > Terminal > Terminal Emulator

LSP Not Working

Symptoms

  • No auto-completion
  • "Go to Definition" doesn't work
  • No error highlighting

Solution

  1. Verify the language server is installed
  2. Check Settings > LSP for configuration
  3. Ensure your project has the required config file:
    • TypeScript: tsconfig.json
    • Python: pyrightconfig.json or pyproject.toml
    • Rust: Cargo.toml

See Setup LSP for detailed instructions.

Slow Performance

Symptoms

  • Editor feels sluggish
  • High CPU usage
  • Slow file opening

Solution

  1. Large files: Files over 10MB may be slow. Consider using a dedicated text editor for very large files.

  2. Many open tabs: Close unused tabs to free memory

  3. LSP indexing: Some language servers need time to index large projects. Wait for initial indexing to complete.

  4. Search scope: Use more specific search patterns and exclude unnecessary directories:

    • Add node_modules, .git, build to ignore patterns

Syntax Highlighting Wrong

Symptoms

  • Code not colored correctly
  • Wrong language detected

Solution

  1. Check the file extension matches the language
  2. Try: View > Syntax > [Language] to manually set
  3. Report unsupported file types for Tree-sitter grammar additions

Workspace Not Opening

Symptoms

  • Project doesn't load
  • Files not showing in Navigator

Solution

  1. Try opening via terminal:

    open -a "Agentastic.dev" /path/to/project

  2. Check folder permissions:

    ls -la /path/to/project

  3. Open a fresh project to verify Agentastic is working

Keyboard Shortcuts Not Working

Symptoms

  • Shortcut does nothing
  • Wrong action triggered

Solution

  1. Check for conflicts in Settings > Keybindings
  2. Verify macOS isn't intercepting the shortcut:
    • System Settings > Keyboard > Keyboard Shortcuts
  3. Try resetting to defaults in Keybindings settings

Auto-Update Issues

Symptoms

  • Updates don't install
  • "Update available" won't dismiss

Solution

  1. Manually download from agentastic.dev/download
  2. Replace the app in /Applications
  3. Relaunch Agentastic

Theme Not Applying

Symptoms

  • Colors look wrong
  • Dark/light mode not switching

Solution

  1. Check Settings > Theme > Match System
  2. Toggle system appearance to trigger refresh
  3. Try selecting a different theme and switching back

Getting Help

If you're still experiencing issues:

  1. Check the FAQ
  2. Search or ask on Discord
  3. Report bugs on GitHub