Skip to main content
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:
PermissionWhyRequired for
AccessibilityWindow management, keystroke injectionWindow tiling, snippet expansion
Input MonitoringGlobal hotkey detectionHold-to-speak, launcher shortcut
MicrophoneVoice dictation (speech-to-text)Optional — voice features
Automation (AppleScript)Selected text capture, system automationExtension 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

Run xcode-select --install and restart your terminal. Verify with swiftc --version.
Ensure Xcode Command Line Tools are installed and up to date:
softwareupdate --install -a
Grant Input Monitoring permission (not just Accessibility) in System Settings → Privacy & Security and restart the app.
Grant Accessibility permission. The window-adjust.swift module checks AXIsProcessTrusted().
Verify Homebrew is installed with brew --version. SuperCmd needs Homebrew-resolved git to clone extensions from GitHub.
Check your Node.js version with node -v — requires 22+. Try deleting node_modules and running npm install again.
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.
Run npm run build:native first. The dev script doesn’t compile Swift binaries automatically.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us