raycast

Build Raycast extensions with React and TypeScript, create Script Commands, and troubleshoot URL schemes and extension execution on macOS.

SKILL.md

GitHub

Raycast macOS Extensible Productivity Launcher AI Skill Guide (Claude)

Overview & Engine Architecture

Raycast is a high-speed, extensible macOS launcher engineered in native Swift with a React/TypeScript Extension Runtime (@raycast/api) running in a secure, embedded Node.js process. Raycast features standalone Script Commands (authored in Bash, Python, Swift, Ruby, or Node.js with special metadata comment headers), Quicklinks, dynamic Snippets with placeholders, AI Chat / Prompt integrations, and an Accessibility-driven Window Management engine. Claude operates as a Principal macOS Tool Architect and Raycast Extension Developer, specializing in React-based Raycast UI extension development, Script Command metadata authoring, TCC Accessibility permission diagnostics, and deep raycast:// URL scheme integration.

Raycast Multi-Tier Architecture & Extension Runtime Stack

┌─────────────────────────────────────────────────────────────┐
│                 Raycast Engine Architecture                 │
│                                                             │
│  Presentation & Native Swift Core                           │
│  ├── Low-Latency Swift HUD Window (Floating Global Launcher)│
│  ├── Spotlight Replacement & Global Hotkey Engine (⌘+Space) │
│  └── Accessibility Window Management (`AXUIElement` Engine) │
│                                                             │
│  Extension & React Runtime (`@raycast/api`)                 │
│  ├── Embedded Node.js Worker & React Reconciler             │
│  ├── Component Library (`List`, `Form`, `Detail`, `Grid`)   │
│  └── Action Panel (`ActionPanel`, `Action.CopyToClipboard`) │
│                                                             │
│  Script Commands & IPC Protocol                             │
│  ├── Script Command Runner (Metadata Header Parser)         │
│  └── Deep URL Scheme Engine (`raycast://extensions/...`)    │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

  1. React / TypeScript Extension Authoring: Develop modular Raycast extensions using @raycast/api and @raycast/utils implementing List, Detail, Form, and ActionPanel views with clean state management.
  2. Metadata Script Command Authoring: Write standalone script commands in Bash, Python, or Swift with valid @raycast.schemaVersion, @raycast.title, @raycast.mode, and @raycast.icon headers.
  3. Accessibility Window Snapping Triage: Remediate window management failures by verifying Raycast's AXUIElement Accessibility permissions in macOS System Settings.
  4. Deep Linking & Quicklinks: Construct raycast:// URL schemes to trigger specific commands, execute extension deep links, and load custom AI prompts.

Production TypeScript Code: Custom Raycast Extension Command (@raycast/api)

Save this file as src/search-repositories.tsx inside a Raycast Extension project (npm install @raycast/api @raycast/utils):

// ==============================================================================
// Raycast Extension Command (React / TypeScript): GitHub Repo Switcher
// Fetches, filters, and opens local git repositories in VS Code or Terminal.
// ==============================================================================
import { Action, ActionPanel, Icon, List, showToast, Toast } from "@raycast/api";
import { useExec } from "@raycast/utils";
import { useState } from "react";

interface RepoItem {
  name: string;
  path: string;
}

export default function Command() {
  const [searchText, setSearchText] = useState("");

  // Scan user Projects directory using fast find command
  const { isLoading, data, error } = useExec(
    "find",
    ["/Users/" + process.env.USER + "/Projects", "-maxdepth", "2", "-name", ".git"],
    {
      onError: (err) => {
        showToast({
          style: Toast.Style.Failure,
          title: "Failed to scan projects",
          message: err.message,
        });
      },
    }
  );

  const repos: RepoItem[] = (data || "")
    .split("\n")
    .filter((line) => line.length > 0)
    .map((gitDir) => {
      const repoPath = gitDir.replace(/\/\.git$/, "");
      const repoName = repoPath.split("/").pop() || "Unnamed";
      return { name: repoName, path: repoPath };
    });

  const filteredRepos = repos.filter((r) =>
    r.name.toLowerCase().includes(searchText.toLowerCase())
  );

  return (
    <List
      isLoading={isLoading}
      onSearchTextChange={setSearchText}
      searchBarPlaceholder="Filter local git repositories..."
    >
      {filteredRepos.map((repo) => (
        <List.Item
          key={repo.path}
          icon={Icon.Folder}
          title={repo.name}
          subtitle={repo.path}
          actions={
            <ActionPanel>
              <Action.Open
                title="Open in VS Code"
                target={repo.path}
                application="Visual Studio Code"
              />
              <Action.Open
                title="Open in Terminal"
                target={repo.path}
                application="Terminal"
              />
              <Action.CopyToClipboard title="Copy Path" content={repo.path} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}

Technical Troubleshooting Matrix

Issue & Failure Signature Root Cause Analysis Diagnostic & Resolution Pathway
Window Management Commands (Snap/Resize) Fail Raycast lacks macOS Accessibility permissions to manipulate window bounds via AXUIElement. 1. Open System Settings $\rightarrow$ Privacy & Security $\rightarrow$ Accessibility.<br>2. Toggle Raycast OFF and ON.<br>3. Restart Raycast.
Script Command Does Not Appear in Launcher Script file missing executable bit (chmod +x) or contains malformed @raycast.schemaVersion header. 1. In terminal, run: chmod +x ~/.raycast-scripts/my_script.sh.<br>2. Verify header format: // @raycast.schemaVersion 1 and // @raycast.title My Script.<br>3. In Raycast Preferences $\rightarrow$ Extensions $\rightarrow$ Reload.
npm run dev Fails with Node.js Version Error Raycast API requires Node.js version 18.0.0 or higher. Update Node.js via Homebrew: brew install node or nvm use 20.
Command + Space Opens Apple Spotlight Instead macOS default Spotlight hotkey collision. In System Settings $\rightarrow$ Keyboard $\rightarrow$ Keyboard Shortcuts $\rightarrow$ Spotlight, uncheck Show Spotlight search, then assign ⌘ + Space to Raycast.

Command Line Syntax & Raycast Script Command Header Template

#!/usr/bin/env bash
# ==============================================================================
# Raycast Script Command Template (Save as executable script)
#
# @raycast.schemaVersion 1
# @raycast.title System Memory Free
# @raycast.mode compact
# @raycast.icon 🚀
# @raycast.packageName Developer Utilities
# ==============================================================================
echo "Free Memory: $(vm_stat | grep 'Pages free' | awk '{print $3 * 4096 / 1024 / 1024}') MB"

Essential File Locations

  • Raycast Application Support: ~/Library/Application Support/com.raycast.macos
  • Custom Script Commands: ~/Library/Application Support/com.raycast.macos/script-commands
  • Raycast Preferences: ~/Library/Preferences/com.raycast.macos.plist

Agent Operational Directive

MANDATORY: When authoring Raycast Script Commands, always specify @raycast.schemaVersion 1, assign an appropriate @raycast.mode (compact, fullOutput, or silent), and ensure executable file permissions (chmod +x).