Troubleshooting

Common issues and solutions for SuperCmd development

This guide covers common issues you may encounter when developing SuperCmd and how to resolve them.

Build Issues

swiftc: command not found

Problem: Swift compiler not found when running npm run build:native

Solution:

1. Install Xcode Command Line Tools

   xcode-select --install
   
2. Restart Terminal

   Close and reopen your terminal to refresh PATH

3. Verify Installation

   swiftc --version
   

   You should see Swift version information

npm install fails on native modules

Problem: Installation fails with node-gyp or native module errors

Solution:

1. Update Xcode Command Line Tools

   softwareupdate --install -a
   
2. Check Node.js Version

   node -v
   

   SuperCmd requires Node.js 22+

3. Clean and Reinstall

   rm -rf node_modules package-lock.json
   npm install
   

Apple Silicon (M1/M2/M3) issues

Problem: Build fails or native features don’t work on Apple Silicon Macs

Ensure you’re running the arm64 version of Node.js, not the x64 version via Rosetta

Solution:

# Check your Node.js architecture
node -p "process.arch"
# Should output: arm64

# If it shows x64, reinstall Node.js arm64 version
# Download from: https://nodejs.org/

Native features missing after npm run dev

Problem: Native features don’t work in development mode

Solution:

The dev script doesn’t compile Swift binaries. Run this first:

npm run build:native

Then start development mode:

npm run dev

Runtime Issues

App launches but hotkeys don’t work

Problem: Global hotkeys and launcher shortcut don’t respond

Solution:

1. Grant Input Monitoring Permission

   Go to System Settings → Privacy & Security → Input Monitoring

   Ensure SuperCmd is checked

2. Restart the App

   Quit SuperCmd completely and relaunch

3. Verify Native Binary

   ls -la dist/native/hotkey-hold-monitor
   

   File should exist and be executable

Window management doesn’t work

Problem: Window tiling and positioning features fail

Solution:

1. Grant Accessibility Permission

   Go to System Settings → Privacy & Security → Accessibility

   Ensure SuperCmd is checked

2. Check window-adjust Binary

   The window-adjust.swift binary checks AXIsProcessTrusted()

   ls -la dist/native/window-adjust
   
3. Restart the App

   Quit SuperCmd and relaunch after granting permission

Extensions fail to install

Problem: Extension installation fails with git errors

Solution:

1. Verify Homebrew is Installed

   SuperCmd uses brew-resolved git to clone extensions:

   brew --version
   
2. Install Homebrew if Missing

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
3. Check Git is Available

   which git
   git --version
   
4. Check Console Logs

   Open DevTools (Cmd+Option+I) and look for specific error messages

Voice input not working

Problem: Hold-to-speak or Whisper STT doesn’t work

Solution:

1. Grant Microphone Permission

   Go to System Settings → Privacy & Security → Microphone

   Ensure SuperCmd is checked

2. Grant Speech Recognition Permission

   Go to System Settings → Privacy & Security → Speech Recognition

   Ensure SuperCmd is checked

3. Verify Native Binaries

   ls -la dist/native/speech-recognizer
   ls -la dist/native/microphone-access
   
4. Test Microphone Access

   ./dist/native/microphone-access
   

   Should return “granted” or “denied”

Development Issues

Changes not reflected in app

Problem: Code changes don’t appear after saving

Solution:

Troubleshooting Steps

DevTools won’t open

Problem: Cmd+Option+I doesn’t open Chrome DevTools

Solution:

Ensure you’re running in development mode:

export NODE_ENV=development
export SUPERCMD_OPEN_DEVTOOLS_ON_STARTUP=1
npm run dev

Or manually open from code:

// In main process
mainWindow.webContents.openDevTools();

TypeScript errors in editor

Problem: Editor shows TypeScript errors but build succeeds

Solution:

1. Restart TypeScript Server

   In VS Code: Cmd+Shift+P → “TypeScript: Restart TS Server”

2. Check tsconfig.json

   Verify you’re using the correct tsconfig:

   • tsconfig.main.json for main process
   • tsconfig.json for renderer
3. Reinstall Dependencies

   rm -rf node_modules package-lock.json
   npm install
   

Extension Compatibility Issues

Extension loads but crashes immediately

Problem: Extension starts then fails with errors

Solution:

1. Open DevTools

   Cmd+Option+I to see error messages

2. Check for Missing APIs

   Look for errors about undefined functions or modules. Check CLAUDE.md for API implementation status.

3. Verify Extension Bundling

   Check that esbuild bundled the extension correctly. Look for bundle errors in console.

4. Test in Raycast

   If possible, test the same extension in official Raycast to verify it works there

Extension preferences not working

Problem: Extension can’t read or save preferences

Solution:

Debug Steps

Extension actions don’t fire

Problem: Clicking actions or using shortcuts does nothing

Solution:

1. Check that ActionPanel is rendered
2. Verify action callbacks are defined
3. Look for JavaScript errors in console
4. Test keyboard shortcuts match expected format
5. Check action registry is collecting actions correctly

IPC Issues

IPC calls timeout or fail

Problem: Renderer → Main IPC calls fail or hang

Solution:

1. Verify Handler Exists

   Check that ipcMain.handle() is registered in src/main/main.ts:

   ipcMain.handle('your-channel', async (event, args) => {
     // handler code
   });
   
2. Check Preload Exposure

   Verify the channel is exposed in src/main/preload.ts:

   contextBridge.exposeInMainWorld('electron', {
     ipcRenderer: {
       invoke: (channel, ...args) => ipcRenderer.invoke(channel, ...args)
     }
   });
   
3. Check for Errors

   Add try-catch to both sides:

   // Renderer
   try {
     const result = await window.electron.ipcRenderer.invoke('channel');
   } catch (error) {
     console.error('IPC error:', error);
   }
   
   // Main
   ipcMain.handle('channel', async () => {
     try {
       return await doSomething();
     } catch (error) {
       console.error('Handler error:', error);
       throw error;
     }
   });
   

AI Feature Issues

AI chat not working

Problem: AI responses don’t stream or fail

Solution:

1. Check AI Configuration

   Go to Settings → AI and verify:

   • AI is enabled
   • Provider is selected (OpenAI, Claude, or Ollama)
   • API key is set (if using cloud providers)
2. Test API Key

   Test the API key directly:

   # OpenAI
   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer $OPENAI_API_KEY"
   
   # Anthropic
   curl https://api.anthropic.com/v1/messages \
     -H "x-api-key: $ANTHROPIC_API_KEY" \
     -H "anthropic-version: 2023-06-01"
   
   # Ollama
   curl http://localhost:11434/api/tags
   
3. Check Console Logs

   Open DevTools and look for AI-related errors

4. Verify Streaming Works

   Check that ai-provider.ts is handling streaming correctly

Ollama not connecting

Problem: Ollama integration fails

Solution:

1. Check Ollama is Running

   curl http://localhost:11434/api/tags
   

   Should return list of models

2. Verify Base URL

   In Settings → AI, check ollamaBaseUrl is set to http://localhost:11434

3. Install Models

   ollama pull llama2
   ollama list
   

Performance Issues

App is slow or laggy

Problem: UI feels sluggish or unresponsive

Solution:

Performance Optimization

Large extension lists are slow

Problem: Scrolling through many items is laggy

Solution:

• Implement virtual scrolling for long lists
• Add search filtering to reduce visible items
• Check if pagination is working correctly
• Profile render performance in React DevTools

macOS-Specific Issues

Permission dialogs keep appearing

Problem: macOS asks for permissions repeatedly

Solution:

This happens when the app bundle identifier changes or the app is rebuilt:

1. Go to System Settings → Privacy & Security
2. Remove SuperCmd from all permission lists
3. Relaunch SuperCmd
4. Grant permissions when prompted
5. Restart the app

App crashes on macOS Sonoma

Problem: App crashes or freezes on macOS Sonoma (14.x)

Solution:

1. Update Electron

   Ensure you’re using Electron 28+ which has Sonoma compatibility fixes

2. Check Native Binaries

   Recompile Swift binaries:

   npm run build:native
   
3. Check Console Logs

   Open Console.app and filter for “SuperCmd” to see system-level errors

Getting Help

If you’re still stuck:

1. Search GitHub Issues — Check if someone else has reported the same problem: GitHub Issues

2. Ask on Discord — Join our Discord server for real-time help

3. Create an Issue — If it’s a bug, create a new issue with:

   • macOS version
   • Node.js version (node -v)
   • SuperCmd version
   • Steps to reproduce
   • Console logs (if available)
   • Screenshots (if relevant)

4. Check Documentation — Read CLAUDE.md for architecture details

Next Steps

• Learn about Contributing to SuperCmd
• Understand Code Organization
• Review Testing strategies