Code Organization

Understanding SuperCmd’s codebase structure and architecture

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.

Key Files

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:

Core Hooks

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

Component Runtimes

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

• Learn about Contributing to SuperCmd
• Understand Testing strategies
• Check Troubleshooting for common issues