Home › Raycast extensions › Raycast extension AGENTS.md

Raycast extension AGENTS.md

AGENTS.md for Raycast extensions in TypeScript and React: manifest commands and preferences, @raycast/api components, @raycast/utils hooks, error toasts, and store-ready linting.

AGENTS.mdRaycast extensions

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Raycast extension

## Commands
- `npm run dev` (`ray develop`, hot reload in Raycast) · `npm run build` (`ray build`) · `npm run lint` (`ray lint`; `npm run fix-lint` to autofix)
- Never run `npm run publish` unless asked.

## Manifest (`package.json`)
- Each command is listed in `commands` with `name` matching `src/<name>.tsx`, a clear `title`, `description` and `mode` (`view`, `no-view`, `menu-bar`).
- User settings go in `preferences` (extension- or command-level) with `type`, `required` and `description`; read them with `getPreferenceValues<Preferences>()`. API keys use `type: "password"`.
- Keep `icon`, `categories`, `author` and `license` valid; store linting fails otherwise.

## UI and data
- Build UI only from `@raycast/api` components (`List`, `Grid`, `Detail`, `Form`, `ActionPanel`, `Action`). No custom HTML/CSS.
- Fetch with `@raycast/utils` hooks (`useFetch`, `usePromise`, `useCachedPromise`, `useCachedState`) and pass `isLoading` to the root component. Use `keepPreviousData` and pagination options for search-as-you-type.
- Every list item has a primary action that does the obvious thing (open, copy, paste) and a sensible `ActionPanel` order; add keyboard `shortcut`s for secondary actions.
- Errors: show `showToast({ style: Toast.Style.Failure, title, message })` or `showFailureToast(error)`; never let a command crash silently. Empty states use `List.EmptyView`.
- `no-view` commands finish with `showHUD` or a toast; `menu-bar` commands keep work short and cached.
- Store small data with `LocalStorage` or `Cache`; never write secrets to them. OAuth via `OAuth.PKCEClient` or the utils OAuth helpers.
- Don't run shell commands or AppleScript unless the feature needs it; quote all arguments.

## Done when
`ray lint` and `ray build` pass, and each changed command was opened with `npm run dev` (say if Raycast wasn't available to check).