alivirgo/Major-AI-Skills / plugins/mas-desktop-ops/skills/raycast
raycast
VerifiedBuild Raycast extensions with React and TypeScript, create Script Commands, and troubleshoot URL schemes and extension execution on macOS.
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
- React / TypeScript Extension Authoring: Develop modular Raycast extensions using
@raycast/apiand@raycast/utilsimplementingList,Detail,Form, andActionPanelviews with clean state management. - Metadata Script Command Authoring: Write standalone script commands in Bash, Python, or Swift with valid
@raycast.schemaVersion,@raycast.title,@raycast.mode, and@raycast.iconheaders. - Accessibility Window Snapping Triage: Remediate window management failures by verifying Raycast's
AXUIElementAccessibility permissions in macOS System Settings. - 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.2. Toggle Raycast OFF and ON.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.2. Verify header format: // @raycast.schemaVersion 1 and // @raycast.title My Script.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, orsilent), and ensure executable file permissions (chmod +x).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |