Skip to main content
SuperCmd follows a modular architecture with clear separation between system operations, UI rendering, and extension compatibility. This guide explains how the codebase is organized.

​
Project Structure

launcher/
├── src/
│   ├── main/           # Electron main process
│   ├── renderer/       # React UI (Vite-powered)
│   └── native/         # Swift helpers for macOS
├── extensions/         # Installed extension data
└── dist/              # Build output

​
Main Process (src/main/)

The Electron main process handles system operations, extension management, and IPC communication.

​
Main Process Responsibilities

  • Handles system operations (file system, applications, clipboard)
  • Manages extension loading and execution
  • Provides IPC bridge between main and renderer
  • Manages global shortcuts and window state
  • Executes native Swift binaries

​
Renderer Process (src/renderer/)

The React-based UI that renders the launcher interface and executes extensions.

​
Renderer Structure

src/renderer/
├── types/
│   └── electron.d.ts          # TypeScript types for window.electron IPC
├── styles/                    # Global styles
└── src/
    ├── App.tsx                # Root component — orchestrates hooks and routing
    ├── raycast-api/            # @raycast/api compatibility layer
    ├── hooks/                 # Feature hooks (state + logic, no JSX)
    ├── views/                 # Full-screen view components (pure UI)
    ├── components/            # Reusable React components
    ├── settings/              # Settings window UI
    ├── utils/                 # Pure utility modules
    └── ExtensionView.tsx      # Renders Raycast extensions

​
App.tsx - The Orchestrator

App.tsx is the orchestrator: it wires hooks together and routes to the correct view. Avoid adding business logic directly to it.
The root component composes all hooks and routes to view components based on application state.

​
Hooks (src/renderer/src/hooks/)

Feature hooks contain state and logic without JSX. Each major feature has a dedicated hook:

​
Views (src/renderer/src/views/)

Full-screen view components are pure UI with no business logic. State comes from hooks.
  • AiChatView.tsx — Full-screen AI chat panel
  • CursorPromptView.tsx — Inline/portal AI cursor prompt UI
  • ScriptCommandSetupView.tsx — Script argument collection form
  • ScriptCommandOutputView.tsx — Script stdout/stderr output viewer
  • ExtensionPreferenceSetupView.tsx — Extension preference/argument form

​
Utils (src/renderer/src/utils/)

Pure utility modules with no side-effects:
  • constants.ts — localStorage keys, magic numbers, error strings
  • command-helpers.tsx — filterCommands, icon renderers, display helpers
  • extension-preferences.ts — localStorage helpers, preference hydration

​
Raycast API Layer (src/renderer/src/raycast-api/)

The compatibility layer that implements @raycast/api and @raycast/utils for Raycast extensions.

​
Architecture

The Raycast API is modularized into focused runtime files: 
raycast-api/
├── index.tsx                      # Integration/export surface
├── action-runtime*.tsx            # Action/ActionPanel runtime
├── list-runtime*.tsx              # List runtime
├── form-runtime*.tsx              # Form runtime
├── grid-runtime*.tsx              # Grid runtime
├── detail-runtime.tsx             # Detail runtime
├── menubar-runtime*.tsx           # MenuBarExtra runtime
├── icon-runtime*.tsx              # Icon resolution and rendering
├── platform-runtime.ts            # Platform APIs
├── misc-runtime.ts                # Misc API exports
├── utility-runtime.ts             # Utility helpers
├── storage-events.ts              # Storage change events
├── context-scope-runtime.ts       # Extension context snapshots
├── oauth/                         # OAuth implementation
└── hooks/                         # @raycast/utils hooks

​
Key Runtime Files

​
Raycast API File Map

When working in the Raycast compatibility layer, use this map to find the right file:
  • Top-level wiring: index.tsx
  • Actions: action-runtime*.tsx files
  • Lists: list-runtime*.tsx files
  • Forms: form-runtime*.tsx files
  • Grids: grid-runtime*.tsx files
  • Icons: icon-runtime*.tsx files
  • Platform APIs: platform-runtime.ts
  • Utilities: utility-runtime.ts
  • OAuth: oauth/ directory
  • Hooks: hooks/ directory
See CLAUDE.md - Raycast API File Map for detailed descriptions of each file.

​
Native Modules (src/native/)

Swift binaries for macOS-native features:
  • color-picker.swift — Native color picker
  • snippet-expander.swift — Text snippet expansion
  • hotkey-hold-monitor.swift — Hold-to-speak hotkey detection
  • speech-recognizer.swift — Native speech recognition
  • microphone-access.swift — Microphone permission checking
  • input-monitoring-request.swift — Input monitoring permissions
  • window-adjust.swift — Window management and positioning

​
Building Native Modules

npm run build:native
This compiles all Swift binaries into dist/native/.

​
Extension Execution Model

How Raycast extensions run in SuperCmd:
1

Extension Loading

Extensions are loaded from the Raycast extension registry
2

Code Bundling

Extension code is bundled using esbuild to CommonJS
3

Runtime Shim

A custom require() function provides:
  • React (shared instance with host app)
  • @raycast/api shim (our compatibility layer)
  • @raycast/utils shim (utility hooks and functions)
4

Isolation

Extensions run in isolated contexts but share React with the host to ensure proper React context and hooks work correctly

​
IPC Communication Pattern

Communication between renderer and main process: 
// Renderer: Request data from main process
const result = await window.electron.ipcRenderer.invoke('get-applications');

// Main: Handle IPC request
ipcMain.handle('get-applications', async () => {
  return getApplicationList();
});

// Preload: Expose secure IPC bridge
contextBridge.exposeInMainWorld('electron', {
  ipcRenderer: {
    invoke: (channel, ...args) => ipcRenderer.invoke(channel, ...args)
  }
});

​
Configuration and Settings

​
Settings Storage

All app settings are persisted in: 
~/Library/Application Support/SuperCmd/settings.json

​
Extension Storage

Extensions use:
  • LocalStorage — Persistent storage (per-extension)
  • Cache — Temporary caching (per-extension)
Both are scoped to the extension context and stored separately.

​
Build Output

dist/
├── main/          # Compiled main process (TypeScript → JavaScript)
├── renderer/      # Compiled renderer (Vite build)
└── native/        # Compiled Swift binaries

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us