### Install and Run SuperCmd Locally

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Follow these steps to set up SuperCmd for development, including installing prerequisites and starting the development server.

```bash
xcode-select --install
git clone https://github.com/SuperCmdLabs/SuperCmd.git
cd SuperCmd
npm install

# Build Swift native helpers once (required before first run)
npm run build:native

# Start development (TS watch + Vite dev server + Electron)
npm run dev

# Production build
npm run build

# Package into a distributable .dmg
npm run package

# Build without code signing (for local testing)
npm run package:unsigned

# Check i18n key parity across all locales
npm run check:i18n
```

--------------------------------

### Install Fallback Chain: Source Download + Bun/npm

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Details the fallback installation method involving downloading extension source files and using Bun or npm for dependency installation and building.

```text
- Downloads extension source files from `raw.githubusercontent.com` (30 concurrent HTTP requests)
- File list comes from GitHub Tree API (cached 10 min)
- Installs deps: **Bun first** (auto-downloaded on first use), npm as fallback
- Runs esbuild to build commands
- Falls through if: GitHub is unreachable
```

--------------------------------

### Install Fallback Chain: Git Sparse-Checkout

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Explains the last resort installation method using Git sparse-checkout, which requires Git to be installed on the user's machine.

```text
- `git clone --depth 1 --filter=blob:none --sparse` of raycast/extensions repo
- `git sparse-checkout set "extensions/{name}"`
- Installs deps: Bun first, npm fallback
- Runs esbuild
- Requires git on the user's machine
```

--------------------------------

### Install Fallback Chain: Pre-built Bundle

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Describes the fastest installation method using pre-built bundles from S3. This method avoids the need for npm, Bun, or esbuild on the user's machine.

```text
- Calls `GET /extensions/:name/bundle` on the backend
- Backend returns a pre-signed S3 URL for `bundles/{name}.tar.gz`
- Tarball contains: `package.json` + `assets/` + `.sc-build/*.js` (esbuild output)
- **No npm, no Bun, no esbuild needed** — just download, extract, done
- Falls through if: bundle doesn't exist in S3, backend is down, S3 returns non-200
```

--------------------------------

### Clone SuperCmd Repository and Install Dependencies

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Clone the SuperCmd repository and install Node.js dependencies using npm. This is the first step for development setup.

```bash
git clone https://github.com/SuperCmdLabs/SuperCmd.git
```

```bash
cd SuperCmd
```

```bash
npm install
```

--------------------------------

### Install SuperCmd with Homebrew

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Use this command to install SuperCmd using Homebrew. Ensure Homebrew is installed on your system.

```bash
brew install --cask supercmdlabs/supercmd/supercmd
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Install Xcode Command Line Tools if not already present. This is required for the Swift compiler.

```bash
xcode-select --install
```

--------------------------------

### Install Homebrew

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Install Homebrew package manager if you don't have it. It's used for resolving runtime dependencies like git and npm.

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

--------------------------------

### Getting Application and Text Information

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Retrieves a list of installed applications, the frontmost application's details, and the currently selected text in any application.

```typescript
const apps = await getApplications();
const apps2 = await getApplications('/Applications');
const front = await getFrontmostApplication();
const selected = await getSelectedText();
```

--------------------------------

### Manual Extension Sync Commands

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Provides a step-by-step guide for manually building the extension catalog, uploading it to S3, and triggering a backend re-index.

```bash
# 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
```

--------------------------------

### Troubleshooting npm Install Failures

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Ensure Xcode CLT is installed and up to date for native module installations.

```bash
softwareupdate --install -a
```

--------------------------------

### SuperCmd Extension Architecture Overview

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Illustrates the SuperCmd extension installation and management architecture, including GitHub Actions, the backend API, and the launcher components.

```mermaid
graph TD
  A[GitHub Actions (cron every 6h)] --> B(build-catalog.js → catalog.json → S3 → webhook → DB (extension_catalog table))
  A --> C(build-extensions.js → pre-built .tar.gz bundles → S3 (/bundles/))

  D[supercmd-backend (NestJS)] --> E{REST Endpoints}
  E --> F[GET /extensions/catalog]
  E --> G[GET /extensions/search?q=]
  E --> H[GET /extensions/popular]
  E --> I[GET /extensions/:name]
  E --> J[GET /extensions/:name/bundle]
  E --> K[GET /extensions/:name/screenshots]
  E --> L[POST /extensions/:name/install]
  E --> M[POST /extensions/:name/uninstall]
  E --> N[POST /extensions/webhook/sync]

  O[Launcher (Electron)] --> P(extension-api.ts → API client)
  O --> Q(extension-registry.ts → install orchestrator)
  O --> R(bun-manager.ts → on-demand Bun download & caching)
```

--------------------------------

### SuperCmd Settings Configuration

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Example JSON structure for SuperCmd application settings, including AI and UI configurations.

```json
{
  "globalShortcut": "Alt+Space",
  "openAtLogin": false,
  "uiStyle": "glassy",
  "fontSize": "medium",
  "appLanguage": "system",
  "ai": {
    "enabled": true,
    "provider": "openai",
    "openaiApiKey": "",
    "anthropicApiKey": "",
    "geminiApiKey": "",
    "ollamaBaseUrl": "http://localhost:11434",
    "elevenlabsApiKey": "",
    "supermemoryApiKey": "",
    "supermemoryBaseUrl": "https://api.supermemory.ai",
    "defaultModel": "openai-gpt-4o-mini",
    "speechToTextModel": "native",
    "textToSpeechModel": "edge-tts"
  }
}
```

--------------------------------

### Run Development Server Command

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/dev-notes/UI_IMPROVEMENTS.md

Command to start the SuperCmd development server. This is used for testing the UI improvements.

```bash
npm run dev
```

--------------------------------

### Verify Swift Compiler

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Check if the Swift compiler is installed and accessible by running this command.

```bash
swiftc --version
```

--------------------------------

### Window Management

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Get information about the active window and set window bounds.

```APIDOC
## Window Management

### Description
APIs for retrieving active window information and manipulating window properties.

### Methods
- `getActiveWindow(): Promise<{ id: string; title: string; url?: string }>`: Gets information about the currently active window.
- `setWindowBounds(options: { windowId: string; bounds: { x: number; y: number; width: number; height: number } }): Promise<void>`: Sets the position and dimensions of a specified window.
```

--------------------------------

### Bun Manager Functionality

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Describes the Bun Manager's role in downloading, caching, and utilizing Bun for faster dependency installation, including its behavior during first use.

```text
- Downloads the Bun binary on-demand when first needed (~50MB)
- Cached at `~/Library/Application Support/SuperCmd/bun/bun`
- Used instead of npm for installing extension dependencies (~25x faster)
- Deletes lockfiles (`package-lock.json`, `bun.lockb`, etc.) before running to avoid frozen lockfile errors
- Shows "Setting up installer for first use…" status in the Store tab UI during first download
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/supercmdlabs/supercmd/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for various types of changes.

```text
feat: add clipboard history search
fix: resolve hotkey not registering on Sonoma
docs: update AI setup instructions
chore: remove unused dependencies
test: add unit tests for ai-provider
```

--------------------------------

### Extension Store

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Interact with the extension store to browse, search, install, and uninstall extensions.

```APIDOC
## Extension Store

### Description
Provides an interface to the extension store for managing extensions.

### Methods
- `getCatalog(): Promise<Extension[]>`: Retrieves the entire extension catalog.
- `searchExtensions(query: string, options?: { limit?: number }): Promise<{ results: Extension[]; total: number }>`: Searches for extensions based on a query.
- `installExtension(extensionId: string): Promise<void>`: Installs an extension.
- `uninstallExtension(extensionId: string): Promise<void>`: Uninstalls an extension.
```

--------------------------------

### Internationalization: Locale File Structure

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Example excerpt of an English locale JSON file used for internationalization. Defines keys for UI elements like search and clipboard.

```json
{
  "search": {
    "placeholder": "Search commands...",
    "noResults": "No results for \"{query}\""
  },
  "clipboard": {
    "title": "Clipboard History",
    "empty": "No items in clipboard history",
    "pinned": "Pinned",
    "copyShortcut": "Copy {count} item",
    "copyShortcut_plural": "Copy {count} items"
  }
}
```

--------------------------------

### Discover and Execute Commands

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Scan macOS for installed applications, system settings, extensions, and scripts. Results are cached. Execute commands by their ID.

```typescript
// src/main/commands.ts
// Accessed via IPC from the renderer:
const commands = await window.electron.getCommands(); // returns cached CommandInfo[]

// CommandInfo shape:
interface CommandInfo {
  id: string;          // e.g. 'app-safari', 'system-sleep', 'ext-raycast.github-my-issues'
  title: string;       // e.g. 'Safari', 'Sleep', 'My GitHub Issues'
  subtitle?: string;   // e.g. 'Application', 'System', 'Extension'
  keywords?: string[];
  iconDataUrl?: string;  // base64 PNG or SVG data URL
  iconEmoji?: string;
  iconName?: string;
  category: 'app' | 'settings' | 'system' | 'extension' | 'script';
  path?: string;         // .app path for apps
  mode?: string;         // 'view' | 'no-view' | 'menu-bar' for extensions
  interval?: string;     // background refresh interval e.g. '1m', '12h'
  deeplink?: string;     // 'supercmd://extensions/<owner>/<ext>/<cmd>'
  commandArgumentDefinitions?: Array<{ 
    name: string;
    required?: boolean;
    type?: string;        // 'text' | 'password' | 'dropdown'
    placeholder?: string;
    title?: string;
    data?: Array<{ title?: string; value?: string }>;
  }>;
}

// Execute any discovered command by ID
await window.electron.executeCommand('app-safari');
await window.electron.executeCommand('system-sleep');
await window.electron.executeCommand('ext-raycast.github-my-issues');

// Update hotkey for a command
await window.electron.updateCommandHotkey('system-supercmd-whisper', 'Command+Shift+W');
// Returns: { success: true } or { success: false, error: 'duplicate', conflictCommandId: '...' }

// Toggle a command's enabled state
await window.electron.toggleCommandEnabled('ext-my-extension-cmd', false);
```

--------------------------------

### Start and Stop Settings File Watcher

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Watches the settings file's parent directory for cloud-sync writes and reloads settings. Debounces 400ms and survives atomic rename(2) writes. Call `startSettingsWatcher` after the app is ready and `stopSettingsWatcher` before quitting.

```typescript
// src/main/settings-store.ts
import {
  startSettingsWatcher,
  stopSettingsWatcher,
  setSettingsBroadcaster,
  setExternalSettingsChangeHandler,
  AppSettings,
} from './settings-store';

// Wire up broadcaster — called after every external settings.json change
setSettingsBroadcaster((settings: AppSettings) => {
  // Broadcast to all open BrowserWindows via IPC
  BrowserWindow.getAllWindows().forEach((win) => {
    win.webContents.send('settings-updated', settings);
  });
});

// Register side-effect handler for main-process operations (hotkey re-registration, extension reconciliation)
setExternalSettingsChangeHandler((settings: AppSettings) => {
  reRegisterGlobalShortcut(settings.globalShortcut);
  reconcileInstalledExtensions(settings.installedExtensions);
});

// Start watching (call after app is ready; rearms automatically after location changes)
startSettingsWatcher();

// Stop watching (e.g., before quit)
stopSettingsWatcher();
```

--------------------------------

### Design Hierarchy Example

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/dev-notes/CONSISTENCY_FIX.md

A visual representation of the unified design hierarchy, detailing the structure and styling of the top bar, body content, and footer.

```text
┌────────────────────────────────┐
│ Top Bar                        │ ← Transparent, shows glass
│ - px-4 py-3                    │
│ - text-[15px] font-light       │
│ - tracking-wide                │
├────────────────────────────────┤
│                                │
│ Body Content                   │ ← Transparent, shows glass
│                                │
├────────────────────────────────┤
│ Footer                         │ ← Solid: rgba(18,18,22,0.85)
│ - px-4 py-3.5                  │
│ - Same Actions layout          │
│ - Same kbd badges              │
└────────────────────────────────┘
```

--------------------------------

### SuperCmd Backend API Endpoints

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

The SuperCmd backend provides several API endpoints for managing and discovering extensions. These endpoints are used by the launcher to fetch extension data, bundles, and track installations.

```APIDOC
## GET /extensions/catalog

### Description
Retrieves the full catalog of available extensions from the database.

### Method
GET

### Endpoint
/extensions/catalog

### Response
#### Success Response (200)
- **extensions** (array) - An array of extension objects.
  - **name** (string) - The name of the extension.
  - **description** (string) - A brief description of the extension.
  - **installCount** (integer) - The number of times the extension has been installed.
  - ... (other extension metadata)

### Response Example
{
  "example": "[\n  {\"name\": \"example-extension\", \"description\": \"An example extension\", \"installCount\": 100}\n]"
}
```

```APIDOC
## GET /extensions/search?q={query}

### Description
Performs a fuzzy search for extensions based on the provided query string.

### Method
GET

### Endpoint
/extensions/search?q={query}

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string.

### Response
#### Success Response (200)
- **extensions** (array) - An array of extension objects matching the search query.

### Response Example
{
  "example": "[\n  {\"name\": \"search-result-extension\", \"description\": \"Extension matching search\"}\n]"
}
```

```APIDOC
## GET /extensions/popular

### Description
Retrieves a list of popular extensions, typically sorted by install count.

### Method
GET

### Endpoint
/extensions/popular

### Response
#### Success Response (200)
- **extensions** (array) - An array of popular extension objects.

### Response Example
{
  "example": "[\n  {\"name\": \"popular-extension\", \"description\": \"A highly installed extension\", \"installCount\": 5000}\n]"
}
```

```APIDOC
## GET /extensions/:name

### Description
Retrieves metadata for a specific extension by its name.

### Method
GET

### Endpoint
/extensions/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the extension to retrieve.

### Response
#### Success Response (200)
- **extension** (object) - The metadata object for the specified extension.

### Response Example
{
  "example": "{\"name\": \"specific-extension\", \"description\": \"Details for a specific extension\"}"
}
```

```APIDOC
## GET /extensions/:name/bundle

### Description
Provides a pre-signed S3 URL to download the pre-built bundle of an extension.

### Method
GET

### Endpoint
/extensions/:name/bundle

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the extension whose bundle URL is requested.

### Response
#### Success Response (200)
- **url** (string) - A pre-signed S3 URL for the extension's bundle tarball.

### Response Example
{
  "example": "https://supercmd-bundles.s3.amazonaws.com/bundles/example-extension.tar.gz?AWSAccessKeyId=..."
}
```

```APIDOC
## GET /extensions/:name/screenshots

### Description
Retrieves a list of screenshots for a specific extension.

### Method
GET

### Endpoint
/extensions/:name/screenshots

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the extension.

### Response
#### Success Response (200)
- **screenshots** (array) - An array of URLs for the extension's screenshots.

### Response Example
{
  "example": "[\"https://example.com/screenshot1.png\", \"https://example.com/screenshot2.png\"]"
}
```

```APIDOC
## POST /extensions/:name/install

### Description
Records an extension installation event, typically used to track install counts.

### Method
POST

### Endpoint
/extensions/:name/install

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the extension being installed.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the install was recorded.

### Response Example
{
  "example": "{\"message\": \"Install recorded successfully\"}"
}
```

```APIDOC
## POST /extensions/:name/uninstall

### Description
Records an extension uninstallation event.

### Method
POST

### Endpoint
/extensions/:name/uninstall

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the extension being uninstalled.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the uninstall was recorded.

### Response Example
{
  "example": "{\"message\": \"Uninstall recorded successfully\"}"
}
```

```APIDOC
## POST /extensions/webhook/sync

### Description
Triggers a synchronization of the extension catalog in the backend, typically called after updates to the catalog data in S3.

### Method
POST

### Endpoint
/extensions/webhook/sync

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the sync process has started.

### Response Example
{
  "example": "{\"message\": \"Catalog sync triggered\"}"
}
```

--------------------------------

### Manage Canvas with Electron IPC

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Utilize window.electron.canvas* methods for the Canvas Manager. Includes create, get all, search, scene persistence, thumbnail generation, library management, and export functionalities. Also covers checking/installing Excalidraw bundle.

```typescript
const canvas = await window.electron.canvasCreate({ title: 'Architecture Diagram' });
const all = await window.electron.canvasGetAll();
const results = await window.electron.canvasSearch('architecture');

// Scene persistence (Excalidraw JSON)
const scene = await window.electron.canvasGetScene(canvas.id);
await window.electron.canvasSaveScene(canvas.id, {
  elements: [/* Excalidraw elements */],
  appState: { viewBackgroundColor: '#ffffff' },
});

// Thumbnail (SVG string → stored for list preview)
await window.electron.canvasSaveThumbnail(canvas.id, '<svg>...</svg>');
const thumbnailSvg = await window.electron.canvasGetThumbnail(canvas.id);

await window.electron.canvasTogglePin(canvas.id);
await window.electron.canvasDuplicate(canvas.id);
await window.electron.canvasExport(canvas.id, 'png'); // or 'svg'

// Library (shared shape library)
await window.electron.saveCanvasLibrary([{ type: 'libraryItem', elements: [] }]);
const library = await window.electron.loadCanvasLibrary();

// Open the dedicated Canvas window
await window.electron.openCanvasWindow('edit', JSON.stringify(canvas));

// Check / install the Excalidraw bundle (downloaded separately)
const installed = await window.electron.canvasCheckInstalled();
if (!installed) await window.electron.canvasInstall();

await window.electron.canvasDelete(canvas.id);
```

--------------------------------

### Command Discovery and Execution

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Scan macOS for installed applications, system settings, extensions, and scripts. Retrieve cached command information and execute commands by their ID. Update hotkeys and toggle command enabled states.

```APIDOC
## Command Discovery — `getAvailableCommands` / `CommandInfo`

Scans macOS for all installed apps, System Settings panes, Raycast-compatible extensions, script commands, quick links, and built-in system commands. Results are cached in memory (30-minute TTL) and persisted to a disk cache for instant cold starts.

### Accessing Commands

Accessed via IPC from the renderer:
```typescript
const commands = await window.electron.getCommands(); // returns cached CommandInfo[]
```

### `CommandInfo` Interface

```typescript
interface CommandInfo {
  id: string;          // e.g. 'app-safari', 'system-sleep', 'ext-raycast.github-my-issues'
  title: string;       // e.g. 'Safari', 'Sleep', 'My GitHub Issues'
  subtitle?: string;   // e.g. 'Application', 'System', 'GitHub'
  keywords?: string[];
  iconDataUrl?: string;  // base64 PNG or SVG data URL
  iconEmoji?: string;
  iconName?: string;
  category: 'app' | 'settings' | 'system' | 'extension' | 'script';
  path?: string;         // .app path for apps
  mode?: string;         // 'view' | 'no-view' | 'menu-bar' for extensions
  interval?: string;     // background refresh interval e.g. '1m', '12h'
  deeplink?: string;     // 'supercmd://extensions/<owner>/<ext>/<cmd>'
  commandArgumentDefinitions?: Array<{
    name: string;
    required?: boolean;
    type?: string;        // 'text' | 'password' | 'dropdown'
    placeholder?: string;
    title?: string;
    data?: Array<{ title?: string; value?: string }>;
  }>;
}
```

### Executing Commands

Execute any discovered command by ID:
```typescript
await window.electron.executeCommand('app-safari');
await window.electron.executeCommand('system-sleep');
await window.electron.executeCommand('ext-raycast.github-my-issues');
```

### Updating Command Hotkeys

Update hotkey for a command:
```typescript
await window.electron.updateCommandHotkey('system-supercmd-whisper', 'Command+Shift+W');
// Returns: { success: true } or { success: false, error: 'duplicate', conflictCommandId: '...' }
```

### Toggling Command Enabled State

Toggle a command's enabled state:
```typescript
await window.electron.toggleCommandEnabled('ext-my-extension-cmd', false);
```
```

--------------------------------

### Useful Commands Overview

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

A collection of commands for development, building, packaging, and utility tasks.

```bash
npm run dev              # Start local development (watch + Vite + Electron)
```

```bash
npm run build            # Build main, renderer, and native modules
```

```bash
npm run build:main       # Compile Electron main process TypeScript
```

```bash
npm run build:renderer   # Build renderer with Vite
```

```bash
npm run build:native     # Compile Swift helpers and native modules
```

```bash
npm run package          # Build and package app with electron-builder
```

```bash
npm run package:unsigned # Build unsigned package for local testing
```

```bash
npm run check:i18n       # Check internationalization strings
```

--------------------------------

### Build for Production

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Builds the application for production by running main, renderer, and native module builds in sequence.

```bash
npm run build
```

--------------------------------

### Manage Quick Links

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Bookmark URLs with optional dynamic field substitution and launch them directly. Specify an application to open the URL with.

```typescript
// Accessed via window.electron IPC from the renderer

const link = await window.electron.quickLinkCreate({
  title: 'GitHub Repo',
  url: 'https://github.com/{owner}/{repo}',
  application: 'com.google.Chrome', // optional bundle ID to open with
});

await window.electron.quickLinkUpdate(link.id, { title: 'My GitHub Repo' });
const all = await window.electron.quickLinkGetAll();
const results = await window.electron.quickLinkSearch('github');

// Get dynamic fields ({owner}, {repo})
const fields = await window.electron.quickLinkGetDynamicFields(link.id);
// [{ key: 'owner', name: 'owner' }, { key: 'repo', name: 'repo' }]

// Open with dynamic values substituted
await window.electron.quickLinkOpen(link.id, { owner: 'SuperCmdLabs', repo: 'SuperCmd' });
// Opens: https://github.com/SuperCmdLabs/SuperCmd in Chrome

await window.electron.quickLinkDuplicate(link.id);
await window.electron.quickLinkDelete(link.id);
```

--------------------------------

### Build Native Modules

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Compiles all Swift binaries and native Node modules. Run this before your first development run.

```bash
npm run build:native
```

--------------------------------

### Auto-update

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Functions for managing application auto-updates, including checking for, downloading, and installing updates.

```APIDOC
## appUpdaterGetStatus

### Description
Retrieves the current status of the application auto-updater.

### Method
`await window.electron.appUpdaterGetStatus()`

### Response
#### Success Response (200)
- **state** (string) - The current state of the updater (e.g., 'downloaded', 'checking').
- **currentVersion** (string) - The currently installed version.
- **latestVersion** (string) - The latest available version.
```

```APIDOC
## appUpdaterCheckForUpdates

### Description
Initiates a check for available application updates.

### Method
`await window.electron.appUpdaterCheckForUpdates()`
```

```APIDOC
## appUpdaterDownloadUpdate

### Description
Downloads the latest available application update.

### Method
`await window.electron.appUpdaterDownloadUpdate()`
```

```APIDOC
## appUpdaterQuitAndInstall

### Description
Restarts the application and installs any downloaded updates.

### Method
`await window.electron.appUpdaterQuitAndInstall()`
```

--------------------------------

### Initialize SuperCmd Renderer Theme

Source: https://github.com/supercmdlabs/supercmd/blob/main/src/renderer/index.html

This script detects the system's preferred color scheme and applies it to the document. It also handles storing and retrieving theme preferences from local storage.

```javascript
(function () { var themeMediaQuery = '(prefers-color-scheme: dark)'; var prefersDarkFromSystem = !!( window.matchMedia && window.matchMedia(themeMediaQuery).matches ); try { var key = 'sc-theme-preference'; var stored = localStorage.getItem(key); var preference = stored === 'light' || stored === 'dark' || stored === 'system' ? stored : 'system'; if (stored !== preference) { localStorage.setItem(key, preference); } var prefersDark = preference === 'dark' || (preference === 'system' && prefersDarkFromSystem); document.documentElement.classList.toggle('dark', prefersDark); document.documentElement.style.colorScheme = prefersDark ? 'dark' : 'light'; } catch { document.documentElement.classList.toggle('dark', prefersDarkFromSystem); document.documentElement.style.colorScheme = prefersDarkFromSystem ? 'dark' : 'light'; } })();
```

--------------------------------

### Manage Application Auto-Updates

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Check for, download, and install application updates. Provides status information about the update process.

```javascript
const updateStatus = await window.electron.appUpdaterGetStatus();
// { state: 'downloaded', currentVersion: '1.0.23', latestVersion: '1.0.24', ... }
await window.electron.appUpdaterCheckForUpdates();
await window.electron.appUpdaterDownloadUpdate();
await window.electron.appUpdaterQuitAndInstall();
```

--------------------------------

### Project Structure Overview

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

This outlines the main directories and their purposes within the SuperCmd project. It helps understand where different components like the Electron main process, React renderer, and native Swift code are located.

```text
src/main/        Electron main process, IPC, extension execution, AI, settings
src/renderer/    React UI + Raycast compatibility layer + built-in feature views
src/native/      Swift native helpers (11 binaries)
extensions/      Installed/managed extension data
dist/            Build output
```

--------------------------------

### Package the App

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Builds and packages the application using electron-builder. Output artifacts are generated under `out/`.

```bash
npm run package
```

--------------------------------

### Window Management

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Get the active window information and set window bounds. Useful for arranging or manipulating application windows.

```typescript
const activeWin = await window.electron.getActiveWindow();
```

```typescript
await window.electron.setWindowBounds({
  windowId: activeWin.id,
  bounds: { x: 0, y: 0, width: 960, height: 1080 }, // tile left half
});
```

--------------------------------

### Navigation with useNavigation Hook

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Demonstrates basic navigation between views using the `useNavigation` hook. Use `push` to navigate to a new view and `pop` to return.

```typescript
function MyList() {
  const { push, pop } = useNavigation();
  return (
    <List>
      <List.Item
        title="Open Detail"
        icon={Icon.Text}
        actions={
          <ActionPanel>
            <Action title="Push Detail" onAction={() => push(<DetailView />)} />
            <Action title="Pop" onAction={pop} shortcut={{ modifiers: ['cmd'], key: 'escape' }} />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

--------------------------------

### Extension Store Operations

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Interact with the extension store to fetch catalogs, search for extensions, and install or uninstall them. Use for managing extensions within the application.

```typescript
const catalog = await window.electron.getCatalog();
```

```typescript
const { results, total } = await window.electron.searchExtensions('github', { limit: 10 });
```

```typescript
await window.electron.installExtension('raycast.github');
```

```typescript
await window.electron.uninstallExtension('raycast.github');
```

--------------------------------

### Build Status Summary

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/dev-notes/FINAL_POLISH.md

Displays the build status and compiled renderer size, indicating a successful build.

```text
✓ Main: Compiled
✓ Renderer: 429KB (98KB gzipped)
```

--------------------------------

### Whisper STT: Native macOS Streaming

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Starts and stops native macOS SFSpeechRecognizer for streaming audio. Uses a callback to receive transcribed chunks.

```typescript
await window.electron.whisperStartNative('en-US', { singleUtterance: true });
const unsub = window.electron.onWhisperNativeChunk(({ transcript, isFinal, error, ready, ended }) => {
  if (transcript) showPartialTranscript(transcript);
  if (isFinal) finalizeAndType(transcript!);
});
await window.electron.whisperStopNative();
unsub();
```

--------------------------------

### Backend Module Key Files

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Lists the key files within the SuperCmd backend module, highlighting their roles in handling REST endpoints, caching, search, and S3 integration.

```text
- `extensions.module.ts` — NestJS module
- `extensions.controller.ts` — REST endpoints (public, no auth except webhook)
- `extensions.service.ts` — catalog cache (5-min TTL), fuzzy search (pg_trgm), install tracking, S3 sync
- `extensions-s3.service.ts` — S3 client for reading catalog and generating pre-signed URLs
- `entities/extension-catalog.entity.ts` — TypeORM entity
- `entities/extension-install.entity.ts` — install tracking entity
- `schemas/search.schema.ts` — Joi validation
```

--------------------------------

### Build Status Summary

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/dev-notes/GLASSY_FINAL.md

Provides a summary of the build status, including window dimensions and compiled sizes.

```text
Window: 900×650 (26% larger)
Main: ✅ Compiled
Renderer: ✅ 429KB
```

--------------------------------

### Text-to-Speech (TTS) Control

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Control speech synthesis, including getting status, toggling pause, navigating paragraphs, stopping, and listing available voices. Use for read-aloud features.

```typescript
const status = await window.electron.speakGetStatus();
// { state: 'speaking', text: '...', index: 2, total: 5, wordIndex: 14 }
```

```typescript
await window.electron.speakTogglePause();
```

```typescript
await window.electron.speakNextParagraph();
```

```typescript
await window.electron.speakStop();
```

```typescript
const voices = await window.electron.edgeTtsListVoices();
```

--------------------------------

### Quick Links Manager

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Manage URL bookmarks with optional dynamic field substitution. Create, update, retrieve, search, and open quick links. Supports duplication and deletion.

```APIDOC
## Quick Links Manager

Bookmark URLs with optional dynamic field substitution (e.g., `https://github.com/{repo}`) and launch them directly from the launcher.

Accessed via `window.electron` IPC from the renderer.

### CRUD Operations

```typescript
// Create a new quick link
const link = await window.electron.quickLinkCreate({
  title: 'GitHub Repo',
  url: 'https://github.com/{owner}/{repo}',
  application: 'com.google.Chrome', // optional bundle ID to open with
});

// Update an existing quick link
await window.electron.quickLinkUpdate(link.id, { title: 'My GitHub Repo' });

// Get all quick links
const all = await window.electron.quickLinkGetAll();

// Search quick links
const results = await window.electron.quickLinkSearch('github');
```

### Dynamic Field Introspection

```typescript
// Get dynamic fields for a quick link
const fields = await window.electron.quickLinkGetDynamicFields(link.id);
// [{ key: 'owner', name: 'owner' }, { key: 'repo', name: 'repo' }]
```

### Opening Quick Links

```typescript
// Open a quick link with dynamic values substituted
await window.electron.quickLinkOpen(link.id, { owner: 'SuperCmdLabs', repo: 'SuperCmd' });
// Opens: https://github.com/SuperCmdLabs/SuperCmd in Chrome
```

### Other Operations

```typescript
// Duplicate a quick link
await window.electron.quickLinkDuplicate(link.id);

// Delete a quick link
await window.electron.quickLinkDelete(link.id);
```
```

--------------------------------

### Remove Extension Install/Uninstall Reporting Calls

Source: https://github.com/supercmdlabs/supercmd/blob/main/SECURITY.md

To disable reporting of extension installs and uninstalls, remove the `reportInstall()` and `reportUninstall()` calls from the extension API file. This requires rebuilding the application from source.

```typescript
// In src/main/extension-api.ts
// Remove or comment out reportInstall() and reportUninstall() calls
```

--------------------------------

### Troubleshooting node-gyp Build Errors

Source: https://github.com/supercmdlabs/supercmd/blob/main/README.md

Ensure you are using Node.js version 22 or higher. Try deleting `node_modules` and reinstalling.

```bash
node -v
```

--------------------------------

### Manage Notes with Electron IPC

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Use window.electron.note* methods to interact with the Notes Manager. Supports create, update, get all, search, pin, duplicate, export, import, and delete operations.

```typescript
const note = await window.electron.noteCreate({
  title: 'Meeting Notes',
  content: '## 2025-01-15\n\n- Action items:\n  - [ ] Follow up with design team',
});

await window.electron.noteUpdate(note.id, { content: '## Updated content' });
const all = await window.electron.noteGetAll();
const results = await window.electron.noteSearch('action items');
await window.electron.noteTogglePin(note.id);
await window.electron.noteDuplicate(note.id);

// Export a single note
await window.electron.noteCopyToClipboard(note.id, 'markdown'); // or 'plaintext'
await window.electron.noteExportToFile(note.id, 'markdown');

// Bulk export / import JSON
await window.electron.noteExport();
const { imported, skipped } = await window.electron.noteImport();

// Open the dedicated Notes window
await window.electron.openNotesWindow('edit', JSON.stringify(note));

await window.electron.noteDelete(note.id);
await window.electron.noteDeleteAll();
```

--------------------------------

### Open Launcher Shortcut

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/dev-notes/UI_IMPROVEMENTS.md

Keyboard shortcut to open the SuperCmd launcher. This is the entry point for interacting with the application's features.

```bash
Cmd+Space
```

--------------------------------

### @raycast/utils - Functions

Source: https://github.com/supercmdlabs/supercmd/blob/main/CLAUDE.md

Offers utility functions for tasks like fetching favicons, generating avatars, running AppleScript, displaying toasts, creating deeplinks, and executing SQL queries.

```APIDOC
## @raycast/utils - Functions

### Description
Offers utility functions for tasks like fetching favicons, generating avatars, running AppleScript, displaying toasts, creating deeplinks, and executing SQL queries.

### Implemented Functions

- `getFavicon`: Favicon fetching
- `getAvatarIcon`: SVG avatar from name initials with deterministic colors
- `getProgressIcon`: SVG circular progress indicator
- `runAppleScript`: AppleScript execution
- `showFailureToast`: Error toast helper
- `createDeeplink`: Generate deeplink URIs for extensions/scripts
- `executeSQL`: Standalone SQLite query execution
- `withCache`: Cache wrapper for async functions with maxAge/validate
```

--------------------------------

### Load and Save Application Settings

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Demonstrates how to load current application settings and persist updated settings, including AI configurations. Sensitive AI keys are stored in an encrypted vault.

```typescript
// src/main/settings-store.ts

import { loadSettings, saveSettings, AppSettings, AISettings } from './settings-store';

// Load current settings (cached in memory after first read)
const settings: AppSettings = loadSettings();
console.log(settings.globalShortcut); // "Alt+Space"
console.log(settings.ai.provider);    // "openai"

// Patch and persist settings (merges with current; sensitive AI keys go to vault)
const updated: AppSettings = saveSettings({
  globalShortcut: 'Command+Space',
  fontSize: 'large',          // 'extra-small' | 'small' | 'medium' | 'large' | 'extra-large'
  uiStyle: 'glassy',          // 'default' | 'glassy'
  navigationStyle: 'vim',     // 'vim' | 'macos'
  appLanguage: 'en',          // 'system' | 'en' | 'zh-Hans' | 'zh-Hant' | 'ja' | 'ko' | 'fr' | 'de' | 'es' | 'ru' | 'it'
  ai: {
    ...settings.ai,
    enabled: true,
    provider: 'openai',
    openaiApiKey: 'sk-...',   // stored in encrypted vault, redacted from disk
    defaultModel: 'openai-gpt-4o-mini',
    speechToTextModel: 'whispercpp',   // 'native' | 'whispercpp' | 'parakeet' | 'openai-whisper'
    textToSpeechModel: 'edge-tts',     // 'edge-tts' | 'elevenlabs'
  },
  hyperKey: {
    enabled: true,
    sourceKey: 'caps-lock',           // 'caps-lock' | 'left-control' | 'right-option' | ...
    capsLockTapBehavior: 'escape',    // 'escape' | 'nothing' | 'toggle'
  },
  clipboardHistoryRetentionDays: 30,  // 1 | 7 | 30 | 90 | 180 | 365 | null (never prune)
  browserSearch: {
    enabled: true,
    historyRetentionDays: 90,
  },
});

// Example: full default settings shape written to disk at ~/Library/Application Support/SuperCmd/settings.json
const exampleSettingsJson = {
  globalShortcut: 'Alt+Space',
  openAtLogin: false,
  uiStyle: 'glassy',
  fontSize: 'medium',
  appLanguage: 'system',
  ai: {
    enabled: true,
    provider: 'openai',
    openaiApiKey: '',        // always blank on disk; real value is in the encrypted vault
    defaultModel: 'openai-gpt-4o-mini',
    speechToTextModel: 'whispercpp',
    textToSpeechModel: 'edge-tts',
    edgeTtsVoice: 'en-US-EricNeural',
    ollamaBaseUrl: 'http://localhost:11434',
  },
};

```

--------------------------------

### Build Status - Main Process

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/dev-notes/CLIPBOARD_FINAL_v2.md

Indicates the successful compilation status of the main process.

```text
Main process: ✅ Compiled
```

--------------------------------

### Canvas Manager API

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Provides functionalities for creating, retrieving, searching, and managing canvas drawings. Includes operations for saving and loading scenes and thumbnails, pinning, duplicating, exporting, and managing libraries. Also supports opening the Canvas window and installing Excalidraw.

```APIDOC
## Canvas Manager

Freeform drawing and diagramming powered by Excalidraw, with scene persistence, thumbnail generation, and library support.

### Functions

- **canvasCreate(data: { title: string })**: Creates a new canvas.
- **canvasGetAll()**: Retrieves all canvases.
- **canvasSearch(query: string)**: Searches canvases by title.
- **canvasGetScene(id: string)**: Retrieves the Excalidraw scene data for a canvas.
- **canvasSaveScene(id: string, scene: object)**: Saves the Excalidraw scene data for a canvas.
- **canvasSaveThumbnail(id: string, svg: string)**: Saves a thumbnail for a canvas.
- **canvasGetThumbnail(id: string)**: Retrieves the thumbnail for a canvas.
- **canvasTogglePin(id: string)**: Toggles the pinned status of a canvas.
- **canvasDuplicate(id: string)**: Duplicates a canvas.
- **canvasExport(id: string, format: 'png' | 'svg')**: Exports a canvas.
- **saveCanvasLibrary(library: Array<object>)**: Saves a shared shape library.
- **loadCanvasLibrary()**: Loads the shared shape library.
- **openCanvasWindow(mode: 'edit', data: string)**: Opens the dedicated Canvas window.
- **canvasCheckInstalled()**: Checks if Excalidraw bundle is installed.
- **canvasInstall()**: Installs the Excalidraw bundle.
- **canvasDelete(id: string)**: Deletes a specific canvas.
```

--------------------------------

### useExec Hook

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Executes shell commands and returns their output.

```APIDOC
## useExec Hook

### Description
Executes shell commands and returns their output, with options for working directory and environment variables.

### Usage
```typescript
const { data: gitLog, isLoading: gitLoading } = useExec('git', ['log', '--oneline', '-10'], {
  cwd: '/Users/me/my-repo',
  env: { GIT_PAGER: 'cat' },
  stripFinalNewline: true,
});
```

### Parameters
- **command**: The command to execute.
- **args**: An array of arguments for the command.
- **options**: Configuration options, including `cwd`, `env`, and `stripFinalNewline`.
```

--------------------------------

### S3 Bucket Structure for Extensions

Source: https://github.com/supercmdlabs/supercmd/blob/main/docs/extension-install-flow.md

Illustrates the hierarchical organization of extension catalog and bundles within the S3 bucket.

```text
s3://supercmd-extensions/
├── catalog/
│   └── catalog.json          # Full extension metadata index
└── bundles/
    ├── emoji.tar.gz           # Pre-built bundle (~5-500KB each)
    ├── todoist.tar.gz
    ├── world-clock.tar.gz
    └── ... (~1855 bundles)
```

--------------------------------

### Shell Command Execution - useExec

Source: https://context7.com/supercmdlabs/supercmd/llms.txt

Execute shell commands using `useExec`. Specify the command and its arguments, along with optional working directory and environment variables. `stripFinalNewline` is a useful option.

```typescript
import {
  useExec,
} from '@raycast/utils';

// Shell command execution
const { data: gitLog, isLoading: gitLoading } = useExec('git', ['log', '--oneline', '-10'], {
  cwd: '/Users/me/my-repo',
  env: { GIT_PAGER: 'cat' },
  stripFinalNewline: true,
});
```