Skip to main content
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 MonitoringEnsure 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 → AccessibilityEnsure 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 → MicrophoneEnsure SuperCmd is checked
2

Grant Speech Recognition Permission

Go to System Settings → Privacy & Security → Speech RecognitionEnsure 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:

​
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:

​
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:

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us