Development Setup

Set up your local development environment for SuperCmd

This guide will help you get SuperCmd running locally for development and contributions.

Prerequisites

Before you begin, ensure you have the following installed:

SuperCmd requires macOS for development. Native Swift modules won’t compile on Linux or Windows.

• macOS - Required for Swift compilation and native integrations
• Node.js 22+ - Check your version with node -v
• npm - Comes bundled with Node.js
• Xcode Command Line Tools - Required for the Swift compiler (swiftc)
• Homebrew - Used at runtime to resolve git and npm for extension installation

System Dependencies

1. Install Xcode Command Line Tools

   If you don’t have Xcode Command Line Tools installed:

   xcode-select --install
   

   Verify Swift is available:

   swiftc --version
   
2. Install Homebrew

   SuperCmd uses Homebrew-resolved git to clone extensions from GitHub. If you don’t have Homebrew:

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

   Verify installation:

   brew --version
   

Getting Started

1. Clone the repository

   git clone https://github.com/SuperCmdLabs/SuperCmd.git
   cd SuperCmd
   
2. Install dependencies

   npm install
   

   This will install all Node.js dependencies and run electron-builder install-app-deps automatically via the postinstall hook.

3. Build native modules

   The dev script does not compile Swift native helpers. You must build them before your first run.

   npm run build:native
   

   This compiles the Swift binaries into dist/native/:

   • color-picker - Native macOS color picker
   • snippet-expander - Text snippet expansion
   • hotkey-hold-monitor - Global hotkey detection
   • speech-recognizer - Speech-to-text recognizer
   • microphone-access - Microphone permission helper
   • input-monitoring-request - Input monitoring permission helper
   • window-adjust - Window management utilities
4. Run in development mode

   npm run dev
   

   This starts three processes concurrently:

   • TypeScript watch for main process
   • Vite dev server for renderer
   • Electron app in development mode

   The environment variable SUPERCMD_OPEN_DEVTOOLS_ON_STARTUP=1 is set automatically in dev mode to open DevTools on launch.

macOS Permissions

SuperCmd requires several macOS permissions to function properly. You’ll be prompted on first use:

Permission	Why	Required for
Accessibility	Window management, keystroke injection	Window tiling, snippet expansion
Input Monitoring	Global hotkey detection	Hold-to-speak, launcher shortcut
Microphone	Voice dictation (speech-to-text)	Optional — voice features
Automation (AppleScript)	Selected text capture, system automation	Extension actions

You may need to restart the app after granting permissions. If features don’t work, check System Settings → Privacy & Security.

Development Workflow

Making Changes

1. Make your changes in the appropriate directory:

   • src/main/ - Electron main process
   • src/renderer/ - React UI and Raycast API shims
   • src/native/ - Swift native helpers

2. The dev server will hot-reload renderer changes automatically

3. Main process changes require restarting the Electron app

4. Native module changes require running npm run build:native again

Testing Extensions

When working on the Raycast API compatibility layer:

• Test with popular Raycast extensions from the store
• API shims are in src/renderer/src/raycast-api/
• Reference the Raycast API docs
• See CLAUDE.md for the complete API implementation status

Troubleshooting

swiftc: command not found

Run xcode-select --install and restart your terminal. Verify with swiftc --version.

npm install fails on native modules

Ensure Xcode Command Line Tools are installed and up to date:

softwareupdate --install -a

App launches but hotkeys don't work

Grant Input Monitoring permission (not just Accessibility) in System Settings → Privacy & Security and restart the app.

Window management doesn't work

Grant Accessibility permission. The window-adjust.swift module checks AXIsProcessTrusted().

Extensions fail to install

Verify Homebrew is installed with brew --version. SuperCmd needs Homebrew-resolved git to clone extensions from GitHub.

node-gyp build errors

Check your Node.js version with node -v — requires 22+. Try deleting node_modules and running npm install again.

Apple Silicon (M1/M2/M3/M4) issues

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

node -p "process.arch"

Should output arm64.

Native features missing after npm run dev

Run npm run build:native first. The dev script doesn’t compile Swift binaries automatically.

Next Steps

• Learn about the project architecture
• Understand build commands and packaging
• Read the contributing guidelines