DocsHelp
View as Markdown

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:

bash
# 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:
    bash
    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:

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

  2. Check folder permissions:

    bash
    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