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. 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