@kody/raycast

@kody/raycast

Official Raycast mark (brand red #FF6363) from the Raycast press kit. Raycast® is a trademark of Raycast Technologies Ltd. This package is not affiliated with or endorsed by Raycast.

Share this listing as https://kody.codes/@kody/raycast — never a /community/{listing_id} URL.

Intent

Give every Kody account a Raycast (or curl / Shortcuts / Alfred) front door whose commands are execute scripts in this package’s storage. Agents add commands with title, description, icon, and ESM code. The local extension calls minted list-commands / run webhooks (URLs live only in ~/.config/kody/raycast.json — never in chat). Success means a forked copy runs that account’s stored commands with no personal tokens baked into source.

Live @kody/raycast ships empty command storage and lists official kody-scope packages for discovery. Fork or install first for a personal launcher.

Extension source: extension/ in this same repo.

What it does

• Store execute commands in package storage (upsert-command / list-commands / delete-command)
• Run a stored command or ad-hoc ESM via run (minted webhook)
• Discover and invoke other owned packages (list-packages / get-package / invoke)
• Ship a Raycast extension under extension/ (commands list, run-code, set-up)
• Fork playbook via ./adapt

Prerequisites / setup

Preferred auth is minted inbound webhooks — not account secrets and not pasted tokens in chat. Package apps on *.kody.run need a Kody browser handoff, so webhooks are the external-client path.

1. Fork or install this listing when the client should use the user’s packages and command storage.
2. Mint webhooks list-commands and run on the fork (optional: also upsert/delete/list-packages/get-package/invoke/root).
3. Optionally webhookUrlApply each handle to a private GitHub repo the owner controls, then on their machine read config.url via gh api and write ~/.config/kody/raycast.json (mode 0600) with:

{
  "listCommandsWebhookUrl": "<minted list-commands url>",
  "runWebhookUrl": "<minted run url>"
}

4. Import extension/ into Raycast (npm install then Import Extension / npm run dev).
5. Open Kody Commands and refresh after agents call upsert-command.

Agents: see AGENTS.md and ./adapt for the full playbook.

Optional package-app bearer

./setup-launcher-token mints a bearer whose hash lives in package storage and returns apiBaseUrl from the hosted package app context when available. Write apiBaseUrl + token into the same raycast.json only if you intentionally use the package app. Prefer webhooks for Raycast.

Optional invocation token (discovery / invoke)

For HTTP clients that call list-packages / get-package / invoke without webhooks, mint a package invocation token in the browser (./guide returns a prefilled URL). Never paste the token into chat.

Agent command creation

import upsertCommand from 'kody:@kody/raycast/upsert-command'

await upsertCommand({
  title: 'List my Kody packages',
  description: 'Smoke: list-packages via execute',
  icon: 'Box',
  code: `import listPackages from 'kody:@kody/raycast/list-packages'
export default async function main() {
  return await listPackages()
}`,
})

Done when

• ~/.config/kody/raycast.json has listCommandsWebhookUrl + runWebhookUrl
• Kody Commands lists stored commands and runs them
• Agents can upsert-command without asking anyone to paste webhook URLs

Adapt this fork

After community_fork, import ./adapt and follow its steps. Put owner-specific webhook URLs and tokens only in local config / preferences / package storage — never hardcode them in source so the official @kody listing stays generic.

Branding

Keep LICENSE (MIT), ## Intent, and community-icon.svg intact for community listing.