@kentcdodds/raycast

@kentcdodds/raycast

Intent

Give any Kody user a small, generic package that Raycast (or curl, Shortcuts, Alfred, etc.) can call to list saved packages and load export metadata. This is the reusable discovery half of a Raycast + Kody setup — not personal home automations.

When to use

• Build a Raycast (or other local) launcher that browses your Kody packages/exports
• Mint a package-invocation token and call Kody over HTTP from outside the MCP/execute sandbox
• Fork this community listing into your scope, then point your client at raycast

Setup

1. Fork this community package into your Kody account (or keep it if you already have raycast in scope).
2. Review the forked source, then publish it so the exports are live.
3. Create a package invocation token (any package / any export is fine for a personal launcher):

https://heykody.dev/account/package-invocation-tokens/new?name=Personal%20Raycast&packageKodyIds=*&exportNames=*&sources=raycast

4. Call exports as:

POST https://heykody.dev/@YOUR_USERNAME/api/package-invocations/raycast/<export>
Authorization: Bearer <token>
Content-Type: application/json

{"params":{},"source":"raycast","idempotencyKey":"raycast:raycast:list-packages:<uuid>"}

Exports

• . — describe the package
• ./list-packages — list your saved packages (packageId, kodyId, name, tags, …)
• ./get-package — load one package’s export metadata (packageId or kodyId)

Raycast / external client example

Minimal fetch helper you can drop into a Raycast Script Command, a tiny extension, or any local tool:

async function invokeKodyExport(
  username: string,
  kodyId: string,
  exportName: string,
  token: string,
  params: Record<string, unknown> = {},
) {
  const path = [kodyId, ...exportName.split("/").filter(Boolean)]
    .map(encodeURIComponent)
    .join("/")
  const response = await fetch(
    `https://heykody.dev/@${encodeURIComponent(username)}/api/package-invocations/${path}`,
    {
      method: "POST",
      headers: {
        authorization: `Bearer ${token}`,
        "content-type": "application/json",
      },
      body: JSON.stringify({
        params,
        source: "raycast",
        idempotencyKey: `raycast:${kodyId}:${exportName || "root"}:${crypto.randomUUID()}`,
      }),
    },
  )
  const body = await response.json()
  if (!response.ok) {
    throw new Error(`Kody invocation failed (${response.status}): ${JSON.stringify(body)}`)
  }
  return body.result ?? body.data ?? body.output ?? body
}

// List packages for a command picker:
const { packages } = await invokeKodyExport(
  "YOUR_USERNAME",
  "raycast",
  "list-packages",
  process.env.KODY_TOKEN!,
)

// Load exports for one package:
const detail = await invokeKodyExport(
  "YOUR_USERNAME",
  "raycast",
  "get-package",
  process.env.KODY_TOKEN!,
  { packageId: packages[0].packageId },
)

curl

curl -sS -X POST \
  "https://heykody.dev/@YOUR_USERNAME/api/package-invocations/raycast/list-packages" \
  -H "Authorization: Bearer $KODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params":{},"source":"raycast","idempotencyKey":"raycast:raycast:list-packages:1"}'

Building a Raycast extension (optional)

You do not need a Store extension for this to be useful — Script Commands or the snippet above are enough. If you want a full picker/launcher:

1. Create a local Raycast extension with preferences for Kody Base URL, Username, Invocation Token, and optionally Package kody id (default raycast).
2. On “Add command”: call list-packages, then get-package, then save { kodyId, exportName, params } locally.
3. On run: POST to /api/package-invocations/{kodyId}/{exportName} with the saved params and source: "raycast".
4. Keep personal automations in your own packages (e.g. home scenes). This package only does discovery.

In-package example

import listPackages from 'kody:@kentcdodds/raycast/list-packages'
import getPackage from 'kody:@kentcdodds/raycast/get-package'

const { packages } = await listPackages()
const pkg = await getPackage({ kodyId: packages[0]?.kodyId })

After you fork, replace @kentcdodds with your scope in import examples; the live kody.id remains raycast unless you rename it.