Skip to content

Build and share a Raycast extension

Turn a small tool into a command people run from their keyboard launcher — they hit a hotkey, type your command's name, and it runs, right there over whatever they're doing. Your agent scaffolds it; you test it live; then you either list it in the public Raycast Store (one-click install for anyone, after a review) or push it to a private store just for your org (no review, no public listing).

Time: ~5 min to your agent for the scaffold. The un-delegable bits: a free Raycast account, testing it live in Raycast on your own Mac, and — for a public listing — a GitHub account and a review that takes days, not minutes. A private org store skips the review. Last verified: 2026-06-07 · Node version, npm run dev, npm run publish, the PR-review flow, and the private-org owner field checked against developers.raycast.com. [confirmed]

New to all this? Do Set up Claude Code first — the agent writes the TypeScript and runs every command. Unsure how to phrase the ask? How to ask your agent is one screen. Just want someone to run a tool, not bind it to a launcher? A one-command tool is simpler and works on any OS.

Before you begin

  • A Mac (or the Raycast Windows beta). Raycast started as a Mac launcher and that's still its home. A Windows beta exists as of 2026-06 — extensions that don't touch native Mac APIs run on both — but treat Mac as the default and test there. [confirmed] (Windows beta status: raycast.com/changelog/windows, checked 2026-06)
  • Raycast installed and a free Raycast account signed in — the account is what publishing checks against. Installing is one download; the account is one signup. ~5 min once. [confirmed]
  • Claude Code running — ~10 min once. It runs Raycast's project generator, writes the extension's TypeScript/React, and runs npm run dev and npm run publish for you.
  • Node 22.14 or newer, and npm 7+. Raycast's tooling needs them. Don't have Node? Your agent installs it. ~3 min once. [confirmed]
  • For a public Store listing only: a GitHub account — publishing opens a pull request under your name. ~10 min once. (A private org store doesn't touch GitHub.) [confirmed]

New to letting an agent run setup for you? Read How to ask your agent — one screen, then come back.

The one un-delegable click: scaffold from inside Raycast

Raycast generates the starter project from its own launcher, not the terminal — so this first move is yours, by hand, once:

  1. Open Raycast (default hotkey ⌥ Space), type Create Extension, hit return. [confirmed]
  2. Name it, write a one-line description, pick a template (start with Detail for "show some text/result" or Form for "collect input"), pick a parent folder, and confirm with ⌘ ↵. [confirmed]

That drops a ready-to-build extension folder on disk. Everything after this, your agent does.

The default: ask your agent

Point Claude Code at that new folder and say:

This is a Raycast extension scaffold. Build it into a command that <does X>:
<paste your script / describe the tool>.

Use the Raycast API (@raycast/api) — wire the UI in the React component under
./src, run `npm install`, then start `npm run dev` so it loads live in Raycast
for me to test. Keep it to no-native-code APIs so it runs cross-platform. When
it works, stop and ask me whether I'm publishing to the public Store or to my
private org.

Your agent fills in the React component (a Raycast extension is TypeScript/React — the "command" is a component that renders a list, a detail view, or a form), installs dependencies, and starts the dev server. While npm run dev runs, your extension appears at the top of Raycast's search with hot reload — every save shows up instantly. [confirmed]

Test it live

With npm run dev running, open Raycast and your command is already there at the top. Run it, poke at it, then tell your agent what to change — edits appear in Raycast as you save, no restart. [confirmed] Stop the dev server with ⌃ C when you're done; the command stays installed locally for you even after. [confirmed]

This local copy is yours only until you publish. Publishing is the next, separate step — and which way you publish depends on who it's for.

Publish: pick public Store or private org

Both routes run the same one command — npm run publish — but they go to different places. Your agent runs it; what differs is the destination and whether there's a review.

=== "Public Store (anyone, one-click)"

For a tool useful to strangers. Anyone browsing the Raycast Store installs it in one click — but a human reviews it first.

1. **Your agent runs `npm run build`** locally first — it type-checks and catches the obvious rejections before a reviewer sees them. `[confirmed]`
2. **Then `npm run publish`.** It opens a **pull request** in Raycast's public [`raycast/extensions`](https://github.com/raycast/extensions) repo under your GitHub account — so you'll approve a GitHub sign-in (the un-delegable click). `[confirmed]`
3. **Raycast reviews it**, requests changes if needed, then merges. On merge it's **auto-published to the [Store](https://www.raycast.com/store)**. Review takes **days, sometimes longer** — the docs don't promise a turnaround. `[unclear]` (no SLA stated — checked 2026-06)

Your recipient then installs in one click from the Store, or you send them the Store link. `[confirmed]`

=== "Private org (your team only)"

For an internal tool. No review, no public listing — only your org's members can see or install it.

1. **Create an organization** in Raycast (the **Manage Organization** command) and grab its **handle**. `[confirmed]`
2. **Set `"owner": "your-org-handle"`** in the extension's `package.json` — that one field is what routes it to the private store instead of the public one. Your agent edits it. `[confirmed]`
3. **Your agent runs `npm run publish`.** It verifies, builds, and pushes straight to your **private extension store** — no PR, no review. A share link lands on your clipboard. `[confirmed]`

Teammates install from the org store after they've joined via your **Copy Organization Invite Link**. `[confirmed]`

After the first publish, shipping an update is one sentence to your agent — "bump the version and publish again" — same command, same destination.

What the recipient does

  • From the public Store: open the Store (in Raycast or at raycast.com/store), find it, click Install. One click, no terminal, no account beyond their own Raycast. They need Raycast installed — that's their one setup, on a Mac (or the Windows beta). [confirmed]
  • From your private org store: accept your org invite link once, then the extension shows in their store to install the same one-click way. [confirmed]
  • Either way: it lives in their launcher from then on — their hotkey, their command name. They never see your code unless they look it up.

If it doesn't work

  • Extension doesn't appear in Raycast while npm run dev runs → the dev server probably isn't actually running, or it crashed on a type error. Check the terminal for a red error and that the process is alive; a built extension only shows up while npm run dev is going (or after a successful publish). Restart it: tell your agent "re-run npm run dev and show me any errors." [confirmed]
  • npm install or npm run dev fails on a Node error → you're on an old Node. Raycast needs Node 22.14+ and npm 7+; older versions throw cryptic build errors. Ask your agent "check my Node version and upgrade to 22.14+ if it's older." [confirmed]
  • Public review rejected it → the common, documented reasons, all fixable: it still uses Raycast's default icon (you need a real 512×512 PNG); the title is too generic ("Utils", "Converter"); it's missing a category or screenshots; it bundles external analytics or asks for Keychain access (both banned); or package.json lacks your Raycast username in author / an MIT license. Hand the reviewer's comment to your agent — "address this review feedback and re-publish" — and it fixes the metadata. [confirmed]
  • "It worked on my machine but the recipient can't install it" → on the public route, it isn't live until the PR is reviewed and merged — a local dev copy is invisible to everyone else. On the private route, the recipient must have joined your org first. Confirm which route you published to and that the PR merged / the invite was accepted. [confirmed]
  • Confused between the dev copy and the published one → the version from npm run dev is local and temporary (gone when you next clean up); the published one is what others get. If you edit and the change isn't reaching recipients, you forgot to re-publish — bump the version and run npm run publish again. [confirmed]
  • npm run publish says you're not authenticated → log in with npx ray login (your agent can run it), then publish again. [confirmed]
  • Anything else → Raycast's own prepare-for-store guide lists every review rule, and the Slack/community link in their docs is where edge cases get answered.

Prefer to do it by hand?

No agent — just you, Raycast, and a terminal.

  1. In Raycast, run Create Extension, pick a template, and confirm — same first step as above. [confirmed]
  2. In the new folder: npm install && npm run dev. Your command appears in Raycast; edit ./src/index.tsx and saves hot-reload. [confirmed]
  3. Stop with ⌃ C when it's right.
  4. Publish. Run npm run build once to catch errors, then:
    • Public Store: npm run publish → approve the GitHub sign-in → it opens a PR for review. [confirmed]
    • Private org: set "owner": "your-org-handle" in package.json, then npm run publish → straight to your private store. [confirmed]

The exact React/TypeScript for the command body is the part an agent saves you most on — the scaffold and publish steps are quick; writing a good UI by hand is where the time goes.

Watch / read

YouTube blocked transcript pulls on 2026-06-07, so these aren't line-by-line verified — they're picked by channel credibility and a tight on-task title/length. Lean on Raycast's own written guide below if any video drifts.

  • Building my first extension with Claude Code — MinorCo, 6:41. Why this one: the closest to our agent-first path — an agent scaffolds and builds the extension end to end in under seven minutes.
  • Create a Raycast Extension with React & Typescript — Colby Fayock, 17:02. Why this one: a well-known dev educator walking the full build by hand, so you can see what the agent is doing under the hood — longer, but on-task throughout.
  • First look at building a Raycast AI Extension (beta) — Raycast (official), 16:45. Why this one: it's Raycast's own channel, so the project setup and dev loop track the current tooling exactly — skip the AI-specific parts if you just want a plain command. [unclear] — covers the AI-extension variant, not every step maps to a basic extension.

Best written walkthrough: Raycast's own Create your first extension — the authoritative source the Create Extension step, npm install && npm run dev, and the hot-reload loop here were checked against. Pair it with Publish an extension for the Store path and Teams: publish a private extension for the org path. [confirmed]

Sources

Good to know

  • Mac-first, Windows in beta. Raycast is a Mac launcher at heart; a Windows beta is live as of 2026-06 (v0.63), and extensions that avoid native-Mac APIs run on both. If your extension reaches for anything Mac-specific, it's Mac-only — test on Mac and don't promise Windows unless you've checked it there. [confirmed] (Windows changelog)
  • Public publishing is permanent and named. A Store listing carries your name and is public; the code goes through Raycast's open raycast/extensions repo, so don't publish anything secret that way. For internal tools, use the private org store — only members see it. See Who can see it?. [confirmed]
  • The review is a real gate. Unlike pushing to a registry, the public Store has a human in the loop, and the docs don't give a turnaround — budget days and a possible round of requested changes. The private org store has no review, so it's the fast path for "just my team." [confirmed] on the gate; [unclear] on timing (no SLA published — checked 2026-06).
  • Pricing. Raycast itself and publishing to the public Store are free; the private org store is a Raycast for Teams feature whose current plan terms you should re-check live at raycast.com/pro before relying on it. [unclear]