Raycast API

@raycast/api is the software development kit developers use to build extensions for Raycast, the macOS launcher. It ships as a type-only npm package: importing @raycast/api in an extension gives you fully-typed access to a large surface of React UI components (List, Grid, Detail, Form, ActionPanel), system integrations (Clipboard, LocalStorage, Cache, OAuth, Browser Extension bridge), and, more recently, a built-in AI layer (AI.ask, and “Tool” entry points that let an LLM agent call into an extension) — all implemented natively by the Raycast host application at runtime rather than in the published JavaScript.

Alongside the API types, the package bundles the ray command-line tool (built on oclif) that extension authors use to scaffold new extensions from templates, run them in development with hot reload, lint and build them with esbuild, and publish them to the Raycast Store. The github.com/raycast/extensions repository that hosts this package’s source is also the monorepo for the community Store itself: it contains thousands of published extensions alongside the gitbook-authored developer documentation, making the API’s real “under the hood” behavior something developers learn primarily from extensive docs, TSDoc-annotated types, and worked examples rather than by reading an open runtime implementation.

What You Get

• Declarative UI primitives - List, Grid, Detail, and Form React components (each with typed sub-components like List.Item and List.Section) for building Raycast’s native interface without any CSS or manual rendering.
• Action & navigation model - ActionPanel and the Action namespace (e.g. Action.OpenInBrowser, Action.CopyToClipboard) give every list/detail item consistent keyboard-driven actions, plus a useNavigation push/pop stack for multi-screen commands.
• Platform integrations - typed wrappers for Clipboard, LocalStorage, Cache, Toast/HUD/Alert feedback, getPreferenceValues, OAuth.PKCEClient, and a Browser Extension bridge for reading the user’s active tab.
• Built-in AI access - the AI namespace (AI.ask) lets an extension call Raycast’s AI without the developer supplying an API key, and Tool entry points let an installed extension expose functions an AI agent can call and ask the user to confirm.
• The ray CLI - an oclif-based command line (ray develop, ray build, ray lint, ray publish) bundled in the same package for scaffolding extensions from templates, hot-reloading during development, and shipping to the Store.
• Manifest-driven lifecycle - commands, preferences, and tools are declared in the extension’s package.json manifest and instantiated by the Raycast host, so an extension’s structure (entry points, arguments, background refresh) follows one consistent convention across the whole ecosystem.

Common Use Cases

• Quick-action commands - a no-view command that copies a value, runs a script, or calls an API and shows a Toast/HUD result, without ever rendering a screen.
• Searchable list extensions - a List of items (GitHub PRs, Spotify tracks, Doppler secrets) backed by a data fetch, with per-item ActionPanel actions and an isLoading state while data loads.
• Multi-step forms - a Form for structured input (creating a to-do, filing an issue) that submits to an external API and confirms success with a Toast.
• AI-agent tools - extensions that expose a Tool function (with an optional Tool.Confirmation) so Raycast AI or a connected MCP client can invoke the extension’s functionality on a user’s behalf.
• Menu bar utilities - background-refreshing MenuBarExtra commands that surface live status (build state, unread count) directly in the macOS menu bar.

Under The Hood

Architecture The published npm package is intentionally thin: its types/index.d.ts (roughly 9,500 lines) declares the entire React component and function surface — Action, List, Grid, Form, Detail, AI, Cache, Clipboard, OAuth, Tool, and more — as ambient TypeScript types with no corresponding runtime implementation shipped in dist/; the only executable code bundled is the ray CLI’s oclif entry point. The actual behavior behind every exported symbol is supplied at runtime by the closed-source Raycast host application when it loads an extension’s bundle, similar in shape to how the vscode npm package is a type-only contract for the VS Code host. Extensions themselves follow a manifest-driven architecture: package.json declares commands, tools, and preferences, and the host instantiates each entry point’s React tree or callback according to that manifest, giving every extension in the ecosystem the same lifecycle regardless of what it does internally.

Tech Stack The API targets React 19 and Node.js 22+ with TypeScript as the primary authoring language; @types/react and @types/node are peer dependencies pinned to exact versions to keep the type surface stable across extensions. Extension code is bundled with esbuild (a direct dependency of the package) as part of the ray build/ray develop commands, and the CLI itself is composed from @oclif/core plus the autocomplete, help, and not-found oclif plugins. The surrounding raycast/extensions repository is a large TypeScript/React monorepo (thousands of independent extension packages) with its developer documentation authored in GitBook and synced into the repo via dedicated GitHub Actions workflows.

Code Quality No unit test suite ships in the published package — there is no runtime implementation to test, since the actual API behavior lives in the closed-source host. What can be assessed is the type layer itself: every exported component and function carries TSDoc comments with @example blocks showing real usage, @remarks explaining edge cases, and consistent namespacing (Component, Component.Props, Component.SubComponent) throughout the 9,500-line declaration file. Correctness for extension authors is enforced indirectly, through TypeScript’s strict type checking at build time and a companion ESLint configuration (@raycast/eslint-config, referenced from the docs) that the ray lint command runs before publishing.

What Makes It Unique Most extension/plugin APIs for desktop tools expose either a thin scripting hook or a full webview sandbox; Raycast’s API instead gives extensions first-class native React UI components rendered by the host itself, so a list or form looks and behaves identically to Raycast’s own built-in commands with no CSS. Its more recent additions push further: the AI namespace gives every extension access to LLM completions with no API key management by the developer, and Tool/Tool.Confirmation entry points let an installed extension expose callable, user-confirmable functions to an AI agent (including via MCP), turning ordinary extensions into agent-usable tools without a second integration surface.