DOCSEARCHbyAlgolia
Submit Docs

SuperCmd Documentation

repository·main·Indexed 23 days ago

https://github.com/supercmdlabs/supercmd

An open-source, Electron-based launcher for macOS featuring Raycast extension compatibility, AI-native actions, and voice dictation. SuperCmd includes a clipboard manager, window tiling, and deep system integration via Swift binaries. It supports multiple AI providers including OpenAI, Anthropic, Google Gemini, and Ollama, as well as various speech-to-text and text-to-speech engines.

Tokens
21.2K
Snippets
32
Records
122
Agent score
61%

What's inside SuperCmd

  1. Overview of SuperCmd features

    main

    SuperCmd is an open-source macOS launcher that provides Raycast-compatible extension workflows combined with AI-native actions and voice workflows.

    Key Capabilities:

    • Raycast Compatibility: Uses @raycast/api and @raycast/utils shims to run existing Raycast extensions.
    • AI Integration: Includes an AI cursor prompt, AI chat (supporting OpenAI, Anthropic, Ollama, Gemini, and OpenAI-compatible providers), and memory-aware AI via Supermemory.
    • Voice & Speech: Hold-to-speak dictation (Wispr Flow-style) and text-to-speech (Speechify-style) using Edge TTS or ElevenLabs.
    • Productivity Tools: Clipboard history (with Cmd+1–9 shortcuts), snippet expansion, window tiling (24 placement commands), and quick links.
    • System Control: Window management, file search, calendar integration, and system commands (Sleep, Restart, etc.).

  2. Use the Clipboard Manager in SuperCmd

    main

    The Clipboard Manager is a Raycast-inspired tool for managing clipboard history, including text, images, URLs, and file paths.

    Accessing the Manager

    1. Open the SuperCmd launcher (default: Cmd+Space).
    2. Type Clipboard History or clip.
    3. Press Enter.

    Basic Operations

    • Navigate: Use ↑ / ↓ arrow keys to move through history.
    • Paste: Press Enter on a selected item or double-click it to paste into your active application.
    • Search: Type in the search bar to filter history by text content.
    • Filter by Type: Use the tabs at the top to filter by All, Text, Image, URL, or File.
    • Delete: Select an item and press Cmd+Backspace or use the "Delete" button in the preview pane. Use "Clear All" to wipe the entire history.

  3. Set up SuperCmd for development

    main

    To develop SuperCmd locally, you must be on macOS with the following prerequisites installed:

    • Node.js 22+
    • npm
    • Xcode Command Line Tools (for swiftc)
    • Homebrew (used to resolve git and npm for extensions)

    Installation Steps

    1. Install system dependencies:

      xcode-select --install
# Verify Swift
swiftc --version
# Install Homebrew if missing
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    2. Clone and install dependencies:

      git clone https://github.com/SuperCmdLabs/SuperCmd.git
cd SuperCmd
npm install

    3. Build native Swift modules (Required before running):

      npm run build:native

    4. Run in development mode:

      npm run dev
    xcode-select --install
swiftc --version
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
git clone https://github.com/SuperCmdLabs/SuperCmd.git
cd SuperCmd
npm install
npm run build:native
npm run dev

  4. Implement Browser-Search Memory Regression Fix

    main

    This implementation plan outlines how to reduce the renderer's retained heap from ~90 MB back to a baseline of ~45-55 MB by gating data loading and optimizing in-memory indexes when browser search is disabled.

    Architecture Overview

    The fix involves changes to two renderer files:

    1. src/renderer/src/hooks/useBrowserSearch.ts: Gates data loading/indexing behind browserSearch.enabled and settingsLoaded flags, and optimizes the in-memory index.
    2. src/renderer/src/hooks/useWebSearchController.ts: Gates the loading of the bangs catalog via IPC based on the browserSearchEnabled setting.

    Key Technical Goals

    • Gating: Prevent refreshEntries(), refreshTabs(), and IPC calls for bangs from firing if browserSearch.enabled is false.
    • Index Optimization: Drop redundant prefix/contains Maps in buildBrowserEntryIndex and implement an LRU cap of 2,000 entries for the per-entry cache.
    • Memory Normalization: Normalize the DDG bangs catalog once at the IPC boundary to prevent spread-copying in memory.

  5. Gate Bangs IPC Load in `useWebSearchController`

    main

    To prevent the 13,520-entry bangs catalog from occupying renderer memory when browser search is disabled, the useWebSearchController hook must be gated.

    Implementation Steps

    1. Update Options Type: Add browserSearchEnabled: boolean to the UseWebSearchControllerOptions type in src/renderer/src/hooks/useWebSearchController.ts.
    2. Gate Bangs Effect: Modify the useEffect responsible for calling window.electron.webSearchListBangs. If browserSearchEnabled is false, call setWebSearchBangCatalog([]) and return early.
    3. Wire through App.tsx: Pass the browserSearch.enabled value from the useBrowserSearch hook into the useWebSearchController call in App.tsx.

    Verification

    Expected Behavior: With browser search disabled, typing a bang (e.g., !g foo) should be treated as plain text. When enabled, Google bang results should appear.

    type UseWebSearchControllerOptions = {
  launcherInputRef: React.RefObject<HTMLInputElement>;
  expandLauncherForDirectLaunch: () => void;
  submitBrowserSearchRef: React.MutableRefObject<
    (query: string, options?: { focusExistingTab?: boolean }) => void | Promise<boolean>
  >;
  setLauncherSearchQuery: React.Dispatch<React.SetStateAction<string>>;
  setLauncherSelectedIndex: React.Dispatch<React.SetStateAction<number>>;
  rootSearchQuery: string;
  aiMode: boolean;
  t: (key: string, params?: Record<string, string | number>) => string;
  browserSearchEnabled: boolean;
};

  6. Manual Extension Catalog and Bundle Sync

    main

    To manually synchronize the extension catalog and pre-built bundles, follow these steps using the provided scripts and AWS CLI:

    # 1. Build catalog
node supercmd-backend/scripts/build-catalog.js /tmp/catalog-output

# 2. Upload catalog to S3
aws s3 cp /tmp/catalog-output/catalog.json s3://supercmd-extensions/catalog/catalog.json

# 3. Trigger backend re-index
curl -X POST "https://api.supercmd.sh/extensions/webhook/sync" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_SECRET"

# 4. Build pre-built bundles (~35 min)
cd supercmd-backend && npm install esbuild --no-save --prefix scripts
node scripts/build-extensions.js /tmp/catalog-output/catalog.json /tmp/build-output

# 5. Upload bundles to S3
aws s3 sync /tmp/build-output/bundles/ s3://supercmd-extensions/bundles/ \
  --cache-control "public, max-age=3600" --size-only

# 6. Clean up
rm -rf /tmp/catalog-output /tmp/build-output

  7. Use Clipboard Manager Actions

    main

    The Clipboard Manager features a consolidated Actions Bar in the bottom right corner for managing history items. Use these actions to interact with your copied content:

    • Paste (Blue): Copies the selected item to the clipboard and immediately closes the window, allowing for immediate pasting into your target application. This is also triggered by the Enter key.
    • Copy to Clipboard (White/Gray): Copies the selected item to the clipboard without closing the window.
    • Delete (Red): Removes the currently selected item. You can also use the keyboard shortcut Cmd+Backspace.
    • Delete All (Red): Clears the entire clipboard history. This action will prompt you for confirmation.

  8. How to use the Paste feature in SuperCmd

    main

    To copy an item to your clipboard and paste it into another application, follow these steps:

    1. Open SuperCmd.
    2. Search for an item (e.g., "Clipboard History").
    3. Select an item and press Enter.
    4. The SuperCmd window will close, and the item is now copied to your clipboard.
    5. Navigate to your target application and press ⌘V to paste the content.

  9. Configure AI and Memory providers

    main

    AI and Memory features are configured via the app UI in Settings > AI.

    AI Providers

    • OpenAI: Requires openaiApiKey (supports GPT-4o, etc.)
    • Anthropic (Claude): Requires anthropicApiKey (supports Claude 3.5 Sonnet, etc.)
    • Google Gemini: Requires geminiApiKey (supports Gemini 1.5 Pro, etc.)
    • Ollama: Requires ollamaBaseUrl (default: http://localhost:11434)
    • OpenAI-compatible: Requires openaiCompatibleBaseUrl and openaiCompatibleApiKey

    Speech / Voice

    • ElevenLabs TTS: Requires elevenlabsApiKey
    • Edge TTS: Built-in, no key required
    • Native macOS STT: No key required
    • Whisper STT: Runs locally, no key required
    • Parakeet STT: Runs locally via swift-transformers, no key required

    Memory

    • Supermemory: Requires supermemoryApiKey, supermemoryClient, and supermemoryBaseUrl (default: https://api.supermemory.ai). Use supermemoryLocalMode for local instances.

  10. Paste items from SuperCmd

    main

    To paste a clipboard item into your active application, follow these steps:

    1. Open SuperCmd and navigate to the desired item using the arrow keys.
    2. Press Enter on the item. This action copies the content to the system clipboard and immediately closes the SuperCmd window.
    3. Switch to your target application and press ⌘V to paste the content.

    This method uses native macOS clipboard behavior for maximum reliability.

  11. Manage clipboard actions via the Actions dropdown

    main

    You can access advanced actions for clipboard items through the Actions dropdown menu. To open the dropdown, click the Actions button or press ⌘K.

    The dropdown includes the following options:

    • Paste: (indicated with a ↩ symbol) Copies to clipboard and closes the window.
    • Copy to Clipboard: Copies the item without closing the window.
    • Delete: Deletes the selected item (destructive action).
    • Delete All Entries: Clears the entire clipboard history (destructive action).

  12. Run SuperCmd in development mode

    main

    To test the UI improvements and run the application locally, use the following command from the project root. This starts both the main and renderer processes.

    Note: Ensure you have copied some text or images to your clipboard before testing the Enter key behavior to verify the paste functionality.

    npm run dev