# @kody/raycast

Official [Raycast](https://www.raycast.com/press) 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/`](./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:

```json
{
  "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`](./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

```js
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.