raycast-dev

Authoring Raycast Extensions

Overview

Provide expert guidance for building, maintaining, and publishing Raycast extensions using React, TypeScript, and the Raycast API. Support all extension types including standard commands, AI extensions, menu bar extensions, and script commands.

Initial Discovery

Before beginning work, determine the current context by following this workflow:

1. Detect Current Working Directory

Check if currently in a Raycast extension directory:

# Look for Raycast extension indicators
ls -la package.json src/ assets/ 2>/dev/null

Indicators of a Raycast extension:

• package.json with @raycast/api dependency
• src/ directory with .tsx files
• assets/ directory with icon.png
• Commands defined in package.json

2. Identify Extension Type

If in an existing extension, analyze package.json to determine extension type:

Standard Command Extension:

{
  "commands": [
    {
      "name": "search",
      "mode": "view", // ← Indicates standard command
      "title": "Search Items"
    }
  ]
}

AI Extension:

{
  "ai": { "instructions": "..." },  // ← Indicates AI extension
  "tools": [...]  // top-level, not nested inside "ai"
}

Menu Bar Extension:

{
  "commands": [
    {
      "name": "status",
      "mode": "menu-bar", // ← Indicates menu bar extension
      "interval": "5m"
    }
  ]
}

No-View Command:

{
  "commands": [
    {
      "name": "action",
      "mode": "no-view" // ← Background command
    }
  ]
}

3. Understand User Intent

When the user requests changes, clarify:

• For new extensions: Ask about extension type if not specified
• For existing extensions: Analyze current structure and propose changes
• For feature additions: Determine if adding new command or enhancing existing one
• For debugging: Identify error messages and relevant code sections

Core Workflows

Creating a New Extension

When creating a new extension from scratch: