[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M734FG8CQDBPQ694GDYYAEQK":3,"skill-same:01M734FG8CQDBPQ694GDYYAEQK":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M734FG8CQDBPQ694GDYYAEQK","create-owncast-plugin-js",null,"Build a complete Owncast plugin in JavaScript from a plain-language description and hand back an installable .ocpkg file. Use when someone wants to create, build, scaffold, or make an Owncast plugin in JavaScript\u002FNode (a chat bot, chat filter\u002Fmoderation tool, stream-event responder, HTTP page\u002Foverlay\u002Fwidget, admin page, fediverse integration, etc.) without needing to know the SDK internals. If the author hasn't picked a language yet, start from create-owncast-plugin (the router) instead.","owncast\u002Fplugin-sdk","owncast","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F69942503?v=4","01M734F1G4F48EQH3Z6BN0N8TA","Owncast","01M734F1HGY63D9FQQRQKHEW8J",1,"MIT","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002Fsdks\u002Fjs\u002Fcreate-owncast-plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-js\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: create-owncast-plugin-js\ndescription: \"Build a complete Owncast plugin in JavaScript from a plain-language description and hand back an installable .ocpkg file. Use when someone wants to create, build, scaffold, or make an Owncast plugin in JavaScript\u002FNode (a chat bot, chat filter\u002Fmoderation tool, stream-event responder, HTTP page\u002Foverlay\u002Fwidget, admin page, fediverse integration, etc.) without needing to know the SDK internals. If the author hasn't picked a language yet, start from create-owncast-plugin (the router) instead.\"\n---\n\n# Create an Owncast plugin (JavaScript)\n\nThis skill walks any AI assistant through building a working Owncast plugin in\n**JavaScript** for a non-expert user: gather what they want in plain language,\nscaffold the project, write the code and manifest, verify it with tests, and\nproduce the single `.ocpkg` file they upload to their Owncast server. The user\nshould never have to understand the runtime. You do that part.\n\n> **Picking a language?** Owncast plugins can be written in JavaScript or Python.\n> The two SDKs are first-class peers: the same handlers, APIs, permissions, and\n> manifest apply to both, and only the scaffolding and language syntax differ.\n> This skill is the **JavaScript** path. For Python, use `create-owncast-plugin-py`.\n> If the language isn't decided yet, start from the `create-owncast-plugin`\n> router, which gathers the author's intent and dispatches to the right one.\n\nThis file is the complete operating guide. It is written to be tool-agnostic:\nwherever it says \"ask the user,\" use whatever question mechanism your harness\noffers (a structured prompt UI, or just a plain chat question). Wherever it says\n\"run,\" use your shell\u002Fcommand tool.\n\n## What an Owncast plugin is (one paragraph)\n\nA plugin is JavaScript that runs sandboxed inside the Owncast server. It\nsubscribes to events (chat messages, stream start\u002Fstop, fediverse activity) by\ndefining handler functions, and calls back into Owncast through the `owncast.*`\nAPI (send chat, store data, fetch URLs, serve web pages, etc.). A\n`plugin.manifest.json` declares the plugin's identity and the **permissions** it\nneeds. Every API call requires its matching permission, or the host refuses to\nload the plugin. Plugins ship as source and run on the JavaScript engine the\nOwncast host embeds (no wasm compile step). `npm run package` bundles everything\ninto one `.ocpkg` file for distribution.\n\n## The workflow (follow in order)\n\n### Step 1: Understand what they want\n\nAsk the user, in plain language:\n\n1. **What should the plugin be called?** (e.g. \"Welcome Bot\"). Derive a **slug**\n   from it: lowercase, digits and hyphens only, must start with a letter, max 64\n   chars (e.g. `welcome-bot`). If their name can't map to a valid slug, propose\n   one and confirm.\n2. **What should it do?** Get concrete behavior, not a category. \"Greet people\n   when they join,\" \"delete messages containing a word,\" \"show a live chat\n   overlay on a web page,\" \"post to Discord when the stream goes live.\"\n\nThen map their description to capabilities using the **Capability map** below.\nThat tells you which handler(s) to write, which `owncast.*` calls to make, and\nwhich permissions the manifest must declare. If a request needs a high-trust\npermission (`fediverse.post`, `videoconfig.write`, `users.moderate`,\n`network.fetch` to arbitrary hosts, or `auth.gate`, which lets the host require\nthe plugin's login for operator-selected viewer resources), note it back to the\nuser. The server admin will have to approve it.\n\nKeep it small. Build the simplest plugin that does what they asked. You can\nalways add handlers later.\n\n### Step 2: Make sure you have a plugin project\n\n**If your working directory already contains a `plugin.manifest.json`**, you are\nalready inside a scaffolded plugin (this skill may have shipped inside it). Do\n**not** scaffold again. Skip to Step 3 and edit the project in place, using its\nexisting slug.\n\n**Otherwise, scaffold a new project** with the official scaffolder\n(non-interactive, takes the slug as an argument):\n\n```sh\nnpx create-owncast-plugin@latest \u003Cslug>\n```\n\nThis creates a `\u003Cslug>\u002F` directory with `package.json`, `plugin.manifest.json`,\n`src\u002Fplugin.js`, and `__tests__\u002Fplugin.test.js` already wired up. All subsequent\ncommands run **from inside that directory**.\n\n### Step 3: Write the plugin\n\nEdit two files based on what you learned in Step 1:\n\n- **`src\u002Fplugin.js`**: define only the handlers the behavior needs. See\n  **Writing handlers** and the **Capability map**.\n- **`plugin.manifest.json`**: set `name`, `description`, and the exact\n  `permissions` required by the handlers you register and APIs you call. See **The manifest**.\n\nIf the plugin serves web content, add files under `public\u002F` (web-served) or\n`assets\u002F` (host-read for inlined UI). Replace the scaffolded test in\n`__tests__\u002Fplugin.test.js` with scenarios that assert your actual behavior (see\n**Testing**).\n\n**Clear the scaffolded placeholders.** They ship verbatim, so don't leave the\ndefaults:\n\n- Set a real `description` in `plugin.manifest.json` (the scaffold leaves `\"An\n  Owncast plugin\"`).\n- **Fill in `INSTRUCTIONS.md`.** It's bundled into the `.ocpkg` and rendered as\n  an **Instructions** tab on the plugin's page in the Owncast admin. Its only\n  audience is the **person installing and running the plugin** (the Owncast\n  admin \u002F streamer), not you the developer. Write it for them, in plain\n  language: **what the plugin does and how to use it once enabled**, including any\n  settings to configure and what each does, the features it adds and how to use\n  them (e.g. chat commands like `!hello`, what happens automatically), and where\n  any page, button, or tab it adds shows up. You built the plugin, so describe\n  its real behavior concretely and accurately. Always write this to the best of\n  your ability. Don't ship the \"Write anything an Owncast admin should know…\"\n  placeholder and don't leave it empty.\n\n### Step 4: Install, then test\n\n```sh\nnpm install      # one-time, fetches the prebuilt test\u002Fserve host binaries\nnpm test         # builds the plugin, then runs your scenario tests\n```\n\n`npm test` bundles `src\u002Fplugin.js` into `\u003Cslug>.js` and runs `__tests__\u002F*.test.js`\nagainst the real plugin runtime with mocked side effects. A pass means the same\nbehavior in production.\n\n**When the build or tests fail, first classify the failure. They need opposite\nresponses:**\n\n- **A behavior\u002Fassertion failure** (the test ran and the output didn't match, a\n  JS error in your handler, a missing permission for an API you call). This is\n  yours to fix: read the diff, correct `src\u002Fplugin.js`, the manifest, or the\n  expectation, and re-run. Don't package with these unresolved.\n- **A toolchain\u002Fversion-skew failure**, with messages like `\"owncast_\u003Csomething>\" is\n  not exported in module \"extism:host\u002Fuser\"`, or other host\u002Fruntime mismatch\n  errors that fire **before your test logic runs**. This is **not** a bug in your\n  plugin, so don't edit handlers to chase it. It means the installed\n  `@owncast\u002Fplugin-sdk` runtime and its bundled test-host binary are out of sync.\n  Respond by: (1) ensuring the latest versions with\n  `npm install @owncast\u002Fplugin-sdk@latest` and re-run. (2) If it persists, note\n  that the compiled `.ocpkg` is still valid for a current Owncast server (the\n  skew is only in the local test harness), proceed to **Step 5**, and tell the\n  user tests couldn't run locally due to a toolchain version mismatch. Do not\n  loop on it.\n\n(If `npm install` cannot reach the network and the toolchain can't be fetched,\ntell the user that's required once, and continue to write correct code so they\ncan run `npm install && npm test && npm run package` themselves.)\n\n### Step 5: Package and hand off\n\n```sh\nnpm run package\n```\n\n`package` first load-checks the plugin — the same install-time path a real\nOwncast server runs. A handler whose gating permission isn't declared in the\nmanifest (a chat filter without `chat.filter`, a fediverse handler without\n`fediverse.inbound`) aborts packaging with the exact error the server would\ngive at install. Fix the manifest, don't work around the check.\n\nThis produces **`\u003Cslug>.ocpkg`** in the project directory, a single self-contained\nfile bundling the manifest, your plugin source (`\u003Cslug>.js`), and any `public\u002F`\u002F\n`assets\u002F`\u002F`icon.png`\u002F`INSTRUCTIONS.md`. Give the user the path to that file and tell them\nhow to install it:\n\n> Open **Plugins** in your Owncast admin → **Upload plugin** → select\n> `\u003Cslug>.ocpkg`. Then review the **Permissions** tab and toggle **Enabled**.\n> (Alternatively, drop the file into `data\u002Fplugins\u002F` on the server.)\n\nBriefly summarize what the plugin does and which permissions the admin will be\nasked to approve, and why each is needed.\n\n---\n\n## Capability map (intent → handler + API + permission)\n\nMatch the user's described behavior to these rows. Define the listed handler(s),\ncall the listed API, and add the listed permission to the manifest. Several rows\ncombine for richer plugins.\n\n| They want to…                                   | Handler(s)                                   | API call                                  | Permission(s)                          |\n| ----------------------------------------------- | -------------------------------------------- | ----------------------------------------- | -------------------------------------- |\n| React to chat messages                          | `onChatMessage(msg)`                         | —                                         | — (add `chat.send` to reply)           |\n| Reply \u002F post in chat                            | (any handler)                                | `owncast.chat.send(text)` \u002F `.sendAction` | `chat.send`                            |\n| Whisper privately to a sender                   | `onChatMessage`\u002F`filterChatMessage`          | `owncast.chat.replyTo(msg, text)`         | `chat.send`                            |\n| Run chat commands (`!uptime`, etc.)             | `commands: { uptime: { run(ctx) {} } }`      | `ctx.reply` \u002F `ctx.replyPrivately`        | `chat.send` to reply                  |\n| Inspect\u002Fmodify\u002Fdrop every message (moderation)  | `filterChatMessage(msg)`                     | `filter.pass\u002Fmodify\u002Fdrop`                 | `chat.filter` (required for the handler) |\n| Delete a message \u002F kick a client                | (any)                                        | `owncast.chat.deleteMessage` \u002F `.kick`    | `chat.moderate`                        |\n| Read recent chat \u002F list clients                 | (any)                                        | `owncast.chat.history()` \u002F `.clients()`   | `chat.history`                         |\n| React when stream goes live \u002F stops             | `onStreamStarted` \u002F `onStreamStopped`        | —                                         | —                                      |\n| Read live stream state (title, viewers, uptime) | (any)                                        | `owncast.stream.current()`                | `server.read`                          |\n| Read server info \u002F socials \u002F emotes \u002F tags      | (any)                                        | `owncast.server.*()`                      | `server.read`                          |\n| Store per-user or persistent state              | (any)                                        | `owncast.kv.get\u002Fset` (+ `getJSON\u002FsetJSON`)| `storage.kv`                           |\n| Rank or aggregate data (private SQL database)   | (any)                                        | `owncast.sql.exec\u002Fquery\u002FqueryRow`         | `storage.sql`                          |\n| Expose admin-configurable settings              | (read at runtime)                            | `owncast.config.get(key, fallback?)`      | — (declare under `config` in manifest) |\n| Call an external API \u002F webhook                  | (any)                                        | `owncast.http.fetch(url, opts?)`          | `network.fetch` + `network.allowedHosts` |\n| Do delayed \u002F periodic work                      | `onTick({now})` or `owncast.timer.*`         | `owncast.timer.setTimeout\u002FsetInterval`    | — (ambient)                            |\n| Serve a web page \u002F overlay \u002F JSON endpoint      | `onHttpRequest(req)` + files in `public\u002F`    | return `{status, headers, body}`          | `http.serve`                           |\n| Push realtime updates to a browser              | (any)                                        | `owncast.sse.send(channel, event, data)`  | `http.sse`                             |\n| Add an admin settings page in the Owncast UI    | `onHttpRequest` + `public\u002Fadmin\u002F...`         | —                                         | `http.serve` + `admin.pages` manifest  |\n| Add a button under the viewer's stream          | (manifest only, or `owncast.actions.add`)    | —                                         | `ui.modify` (+ `http.serve` if it opens your page) |\n| Inject CSS \u002F JS \u002F HTML into the viewer page     | (manifest `styles`\u002F`scripts`\u002F`extraPageContent`) | dynamic `onPageStyles()` \u002F `onPageScripts()` \u002F `onPageContent({slug,user})` | `ui.modify`                            |\n| Add a tab to the viewer page                    | optional `onTabContent({slug,user})`         | —                                         | `ui.modify` (+ data perms used)        |\n| Upload a file and get a public URL              | (any)                                        | `owncast.storage.upload(name, bytes)`     | `storage.upload`                       |\n| Private server-side files                       | (any)                                        | `owncast.fs.*`                            | `storage.fs`                           |\n| Send Discord \u002F browser-push \u002F fediverse notice  | (any)                                        | `owncast.notifications.*`                 | `notifications.send`                   |\n| Post publicly to the fediverse (high-trust)     | (any)                                        | `owncast.fediverse.post(text)`            | `fediverse.post`                       |\n| React to any verified inbound fediverse activity | `onFediverse(activity)` for raw JSON, plus `onFediverseFollow\u002FLike\u002FRepost\u002FQuote\u002FMention\u002FReply` for specialized payloads | none | `fediverse.inbound` |\n| Read\u002Fchange video\u002Ftranscoding config            | (any)                                        | `owncast.videoConfig.read\u002Fwrite`          | `videoconfig.read` \u002F `videoconfig.write` |\n| Compose with other plugins via custom events    | own local hooks with `on:{}`, emit to `\u003Crecipient-slug>.\u003Chook>` | `owncast.events.emit(type, payload)` | `events.emit` (emitter only) |\n| Gate the site behind a member login (paywall) | `onHttpRequest` (login flow) + `onAuthCheck` (re-validation) | `owncast.users.register` + `owncast.auth.grantSession\u002FendSession` | `auth.gate` + `users.register` (+ `http.serve`); model on `examples\u002Fjs\u002Fgithub-auth` |\n\n**Golden rule:** the `permissions` array must contain exactly the permissions\nrequired by the handlers you register and every `owncast.*` method you call.\nMissing one means the call throws and\u002For the host refuses to load the plugin.\nDon't add permissions you don't use, since admins judge trust by the declared list.\n\n---\n\n## Writing handlers\n\n```js\nconst { definePlugin, owncast, filter } = require(\"@owncast\u002Fplugin-sdk\");\n\nmodule.exports = definePlugin({\n  onChatMessage(msg) {\n    \u002F\u002F msg: { id, user, clientId?, body, timestamp }. msg.user is a ChatUser\n    \u002F\u002F object in production ({id, displayName, scopes?}); older hosts and\n    \u002F\u002F scaffolded test scenarios may send it as a plain display-name string,\n    \u002F\u002F so read the name defensively.\n    const name = typeof msg.user === \"string\" ? msg.user : msg.user?.displayName;\n    if (\u002F^hi\\b\u002Fi.test(msg.body)) {\n      owncast.chat.send(`hello, ${name ?? \"there\"}!`);\n    }\n  },\n});\n```\n\nDefine **only** the handlers you need. The SDK derives event subscriptions from\nwhich handlers exist. Full list of handlers: `onChatMessage`,\n`filterChatMessage`, `onChatUserJoined`, `onChatUserParted`,\n`onChatUserRenamed`, `onMessageModerated`, `onStreamStarted`, `onStreamStopped`,\n`onStreamTitleChanged`, `onFediverse`, `onFediverseFollow\u002FLike\u002FRepost\u002FQuote\u002FMention\u002FReply`,\n`onHttpRequest`, `onTick`, `onSseConnect\u002FDisconnect`, `onTabContent`,\n`onPageContent`, `onPageStyles`, `onPageScripts`, and\n`on: { \"event\"() {} }` for local custom hooks. The host registers each as\n`\u003Cyour-plugin-slug>.event`, which emitters use as the target.\n\nImportant shape\u002Fbehavior notes:\n\n- **`msg.user` is a string *or* an object.** In production it's a `ChatUser`\n  (`{ id, displayName, scopes? }`). Older hosts and the scaffolded test\n  scenarios send a plain display-name string. Read the name defensively:\n  `typeof msg.user === \"string\" ? msg.user : msg.user?.displayName`. For stable\n  per-user state and moderator gating use the object form (`msg.user?.id`,\n  `msg.user?.scopes?.includes(\"MODERATOR\")`), never match on display name, and\n  treat a string or absent user as having no id\u002Fscopes. Declarative command\n  tables handle moderator gating automatically.\n- **Chat text is HTML-escaped on display.** `chat.send`\u002F`sendAction` take plain\n  text. The exception is `chat.system(body)`, whose body renders as HTML, so escape\n  untrusted content yourself.\n- **Filters fail open and are time-capped (50 ms).** `filterChatMessage` must be\n  fast. A filter that errors is treated as `filter.pass()`. Five consecutive\n  failures auto-disable the plugin for the session.\n- **`Date`\u002F`Date.now()` work**, but there is no global `setTimeout`. Use\n  `owncast.timer.*`. Timers don't survive a host restart.\n- **`owncast.sql.*` is one private SQLite database per plugin.** Each `exec` is\n  a single atomic transaction, so a multi-statement schema setup either lands\n  whole or not at all. An unbounded `query` that overruns the host's row or\n  result budget is an error, not a truncated result, so write a `LIMIT`, or use\n  `queryRow` when you only need one row. Plugin databases are not included in\n  Owncast's backups. Worked example: `examples\u002Fjs\u002Fchat-leaderboard`.\n- **Chat commands:** declare a `commands` table in `definePlugin`. Command\n  tables support prefixes, aliases, parsed arguments, moderator gating, and\n  per-user cooldowns. Unknown and gated invocations are silent.\n\n## The manifest\n\n```json\n{\n  \"api\": \"1\",\n  \"name\": \"Welcome Bot\",\n  \"slug\": \"welcome-bot\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Greets people when they join the chat\",\n  \"permissions\": [\"chat.send\"]\n}\n```\n\n- `name`: human-readable, and also the default chat-bot display name. `bot.displayName` overrides it.\n- `slug`: canonical id (URL prefix, storage namespace, filename). Auto-derived from `name` if omitted, but keep it explicit and matching the directory.\n- `permissions`: see the Capability map. Declare exactly what you use.\n- `config`: optional admin-configurable settings: `{ \"key\": { \"type\": \"string|number|boolean\", \"default\": ..., \"description\": \"...\" } }`, read via `owncast.config.get`.\n- UI fields (`actions`, `styles`, `scripts`, `extraPageContent`, `tabs`) all require `ui.modify`.\n- `tabs`: `{ \"tab-slug\": { \"title\": \"Tab label\", \"content\": \"optional.html\" } }`.\n- `admin.pages`: `{ \"\u002Fadmin\u002F*\": { \"title\": \"Settings\" } }`. The host auth-gates matching path keys.\n- **`network.fetch` also requires `network` block:** `\"network\": { \"allowedHosts\": [\"api.example.com\", \"*.weather.com\"] }`. The bare wildcard `\"*\"` is allowed but must be written explicitly. The host rejects the load if `network.fetch` is granted without `allowedHosts`.\n\n## Project layout\n\n```\n\u003Cslug>\u002F\n├── plugin.manifest.json   # identity + permissions\n├── icon.png               # optional: admin-list icon (bundled automatically)\n├── INSTRUCTIONS.md        # optional: rendered as an admin tab\n├── src\u002Fplugin.js          # your code\n├── public\u002F                # optional: served at \u002Fplugins\u002F\u003Cslug>\u002F...\n├── assets\u002F                # optional: host-read for inlined styles\u002Fscripts\u002FHTML (NOT URL-served)\n└── __tests__\u002F*.test.js    # scenario tests\n```\n\n## Testing\n\nReplace the scaffolded test with scenarios for your behavior. Each scenario\ndispatches events and asserts on observed side effects:\n\n```js\nconst { runScenarios } = require(\"@owncast\u002Fplugin-sdk\u002Ftesting\");\n\nrunScenarios([\n  {\n    name: \"greets joining users\",\n    events: [{ event: \"chat.user.joined\", payload: { id: \"u1\", displayName: \"alice\" } }],\n    expect: { chatSends: [\"welcome, alice!\"] },\n  },\n]);\n```\n\nStep types: `event`, `filter` (with `expect: {action, payload?, reason?}`),\n`http` (`{method, path, expect:{status, bodyContains?}}`), `tabContent`,\n`pageContent`, `pageStyles`, `pageScripts`, and `authCheck` (drives\n`onAuthCheck` for `auth.gate` plugins). Final-state assertions include `chatSends`, `chatActions`,\n`chatSystems`, `chatTo`, `sseSends`, `emits`, `kv`, `httpRequests`,\n`videoConfigWrites`. Seed inputs with `given` (`given.kv`, `given.config`,\n`given.stream`, `given.users`, `given.httpResponses`, etc.). Use `authenticated: true` or a\n`user` object on `http` steps to test admin\u002Fuser-gated endpoints.\n\nShapes that trip people up:\n\n- **A chat event's `user` can be a string or an object.** The scaffolded tests\n  use the string shorthand (`payload: { user: \"alice\", ... }`), while production sends\n  a `{ id, displayName, scopes? }` object. Keep your test payloads and handler in\n  sync: if the handler reads `msg.user.id` \u002F `.scopes` (or `.displayName`), pass\n  an object (`user: { id: \"u1\", displayName: \"alice\" }`). If it reads a bare\n  string, pass a string. The defensive read above works with both.\n- **`config` values come from the manifest defaults** unless the scenario seeds\n  admin overrides via `given.config` (`\"given\": { \"config\": { \"key\": \"value\" } }`).\n  `owncast.config.get(\"key\")` returns the override when seeded, otherwise the\n  `default` declared under `config` in `plugin.manifest.json`. Test both paths.\n- **One `given.httpResponses` entry per URL pattern.** The `url` is a glob\n  matched against the full URL (`\"https:\u002F\u002Fapi.example.com\u002Fuser*\"` covers any\n  query string) and the first match wins, so a sequence where the same URL must\n  answer differently across calls can't be modeled by fixtures.\n\nFor interactive iteration, `npm run serve` hosts the plugin on\n`http:\u002F\u002Flocalhost:8080\u002Fplugins\u002F\u003Cslug>\u002F` with `\u002F_dev\u002F*` endpoints to fire events.\n\n## Common recipes (copy and adapt)\n\n**Greeter** (`permissions: [\"chat.send\"]`):\n```js\nmodule.exports = definePlugin({\n  onChatUserJoined(user) { owncast.chat.send(`welcome, ${user.displayName}!`); },\n});\n```\n\n**Word filter** (`permissions: [\"chat.filter\"]`):\n```js\nmodule.exports = definePlugin({\n  filterChatMessage(msg) {\n    return \u002Fbadword\u002Fi.test(msg.body) ? filter.drop(\"blocked\") : filter.pass();\n  },\n});\n```\n\n**External fetch on command** (`permissions: [\"chat.send\",\"network.fetch\"]`, `network.allowedHosts: [\"api.ipify.org\"]`):\n```js\nmodule.exports = definePlugin({\n  onChatMessage(msg) {\n    if (msg.body.trim() !== \"!ip\") return;\n    const res = owncast.http.fetch(\"https:\u002F\u002Fapi.ipify.org?format=json\");\n    if (res.status === 200) owncast.chat.send(`IP: ${JSON.parse(res.body).ip}`);\n  },\n});\n```\n\n**Notify Discord on stream start** (`permissions: [\"notifications.send\"]`):\n```js\nmodule.exports = definePlugin({\n  onStreamStarted(info) { owncast.notifications.discord(`Live now: ${info.title || \"stream\"}`); },\n});\n```\n\n## Where to go deeper\n\nThe repository's `docs\u002FPLUGIN_AUTHOR_GUIDE.md` is the exhaustive reference\n(every handler, every API method, limits, SSE, admin pages, action buttons,\nviewer-page injection, full testing model). Read it when a request needs a\nfeature this summary only outlines. Worked examples live in `examples\u002Fjs\u002F`.\n\nThe public documentation at \u003Chttps:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins> covers the same\nground for authors who want a web reference: the\n[JavaScript SDK](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fsdks\u002Fjavascript),\n[Manifest](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fmanifest),\n[Events](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fevents),\n[Owncast APIs](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fapis),\n[Permissions](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpermissions),\n[Testing](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Ftesting), and\n[Packaging](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpackaging) pages.\n\n## Checklist before you hand off the .ocpkg\n\n- [ ] `name`, `slug`, real `description` set (not the `\"An Owncast plugin\"` placeholder), and slug valid and matches the directory.\n- [ ] `permissions` lists exactly the APIs the code calls, no more and no less.\n- [ ] `network.allowedHosts` present if `network.fetch` is used, `ui.modify` present for any UI field, and `chat.filter` present if `filterChatMessage` is defined.\n- [ ] `INSTRUCTIONS.md` is written for the person installing\u002Frunning the plugin (what it does and how to use it once enabled), not the scaffold placeholder, and it ships in the `.ocpkg`.\n- [ ] `npm test` passes, or, if it failed only on a toolchain\u002Fversion skew (not your logic), you confirmed that and said so.\n- [ ] `npm run package` produced `\u003Cslug>.ocpkg`, you gave the user its path and install instructions, and noted which permissions the admin must approve.\n","# Create an Owncast plugin (JavaScript)\n\nThis skill walks any AI assistant through building a working Owncast plugin in\n**JavaScript** for a non-expert user: gather what they want in plain language,\nscaffold the project, write the code and manifest, verify it with tests, and\nproduce the single `.ocpkg` file they upload to their Owncast server. The user\nshould never have to understand the runtime. You do that part.\n\n> **Picking a language?** Owncast plugins can be written in JavaScript or Python.\n> The two SDKs are first-class peers: the same handlers, APIs, permissions, and\n> manifest apply to both, and only the scaffolding and language syntax differ.\n> This skill is the **JavaScript** path. For Python, use `create-owncast-plugin-py`.\n> If the language isn't decided yet, start from the `create-owncast-plugin`\n> router, which gathers the author's intent and dispatches to the right one.\n\nThis file is the complete operating guide. It is written to be tool-agnostic:\nwherever it says \"ask the user,\" use whatever question mechanism your harness\noffers (a structured prompt UI, or just a plain chat question). Wherever it says\n\"run,\" use your shell\u002Fcommand tool.\n\n## What an Owncast plugin is (one paragraph)\n\nA plugin is JavaScript that runs sandboxed inside the Owncast server. It\nsubscribes to events (chat messages, stream start\u002Fstop, fediverse activity) by\ndefining handler functions, and calls back into Owncast through the `owncast.*`\nAPI (send chat, store data, fetch URLs, serve web pages, etc.). A\n`plugin.manifest.json` declares the plugin's identity and the **permissions** it\nneeds. Every API call requires its matching permission, or the host refuses to\nload the plugin. Plugins ship as source and run on the JavaScript engine the\nOwncast host embeds (no wasm compile step). `npm run package` bundles everything\ninto one `.ocpkg` file for distribution.\n\n## The workflow (follow in order)\n\n### Step 1: Understand what they want\n\nAsk the user, in plain language:\n\n1. **What should the plugin be called?** (e.g. \"Welcome Bot\"). Derive a **slug**\n   from it: lowercase, digits and hyphens only, must start with a letter, max 64\n   chars (e.g. `welcome-bot`). If their name can't map to a valid slug, propose\n   one and confirm.\n2. **What should it do?** Get concrete behavior, not a category. \"Greet people\n   when they join,\" \"delete messages containing a word,\" \"show a live chat\n   overlay on a web page,\" \"post to Discord when the stream goes live.\"\n\nThen map their description to capabilities using the **Capability map** below.\nThat tells you which handler(s) to write, which `owncast.*` calls to make, and\nwhich permissions the manifest must declare. If a request needs a high-trust\npermission (`fediverse.post`, `videoconfig.write`, `users.moderate`,\n`network.fetch` to arbitrary hosts, or `auth.gate`, which lets the host require\nthe plugin's login for operator-selected viewer resources), note it back to the\nuser. The server admin will have to approve it.\n\nKeep it small. Build the simplest plugin that does what they asked. You can\nalways add handlers later.\n\n### Step 2: Make sure you have a plugin project\n\n**If your working directory already contains a `plugin.manifest.json`**, you are\nalready inside a scaffolded plugin (this skill may have shipped inside it). Do\n**not** scaffold again. Skip to Step 3 and edit the project in place, using its\nexisting slug.\n\n**Otherwise, scaffold a new project** with the official scaffolder\n(non-interactive, takes the slug as an argument):\n\n```sh\nnpx create-owncast-plugin@latest \u003Cslug>\n```\n\nThis creates a `\u003Cslug>\u002F` directory with `package.json`, `plugin.manifest.json`,\n`src\u002Fplugin.js`, and `__tests__\u002Fplugin.test.js` already wired up. All subsequent\ncommands run **from inside that directory**.\n\n### Step 3: Write the plugin\n\nEdit two files based on what you learned in Step 1:\n\n- **`src\u002Fplugin.js`**: define only the handlers the behavior needs. See\n  **Writing handlers** and the **Capability map**.\n- **`plugin.manifest.json`**: set `name`, `description`, and the exact\n  `permissions` required by the handlers you register and APIs you call. See **The manifest**.\n\nIf the plugin serves web content, add files under `public\u002F` (web-served) or\n`assets\u002F` (host-read for inlined UI). Replace the scaffolded test in\n`__tests__\u002Fplugin.test.js` with scenarios that assert your actual behavior (see\n**Testing**).\n\n**Clear the scaffolded placeholders.** They ship verbatim, so don't leave the\ndefaults:\n\n- Set a real `description` in `plugin.manifest.json` (the scaffold leaves `\"An\n  Owncast plugin\"`).\n- **Fill in `INSTRUCTIONS.md`.** It's bundled into the `.ocpkg` and rendered as\n  an **Instructions** tab on the plugin's page in the Owncast admin. Its only\n  audience is the **person installing and running the plugin** (the Owncast\n  admin \u002F streamer), not you the developer. Write it for them, in plain\n  language: **what the plugin does and how to use it once enabled**, including any\n  settings to configure and what each does, the features it adds and how to use\n  them (e.g. chat commands like `!hello`, what happens automatically), and where\n  any page, button, or tab it adds shows up. You built the plugin, so describe\n  its real behavior concretely and accurately. Always write this to the best of\n  your ability. Don't ship the \"Write anything an Owncast admin should know…\"\n  placeholder and don't leave it empty.\n\n### Step 4: Install, then test\n\n```sh\nnpm install      # one-time, fetches the prebuilt test\u002Fserve host binaries\nnpm test         # builds the plugin, then runs your scenario tests\n```\n\n`npm test` bundles `src\u002Fplugin.js` into `\u003Cslug>.js` and runs `__tests__\u002F*.test.js`\nagainst the real plugin runtime with mocked side effects. A pass means the same\nbehavior in production.\n\n**When the build or tests fail, first classify the failure. They need opposite\nresponses:**\n\n- **A behavior\u002Fassertion failure** (the test ran and the output didn't match, a\n  JS error in your handler, a missing permission for an API you call). This is\n  yours to fix: read the diff, correct `src\u002Fplugin.js`, the manifest, or the\n  expectation, and re-run. Don't package with these unresolved.\n- **A toolchain\u002Fversion-skew failure**, with messages like `\"owncast_\u003Csomething>\" is\n  not exported in module \"extism:host\u002Fuser\"`, or other host\u002Fruntime mismatch\n  errors that fire **before your test logic runs**. This is **not** a bug in your\n  plugin, so don't edit handlers to chase it. It means the installed\n  `@owncast\u002Fplugin-sdk` runtime and its bundled test-host binary are out of sync.\n  Respond by: (1) ensuring the latest versions with\n  `npm install @owncast\u002Fplugin-sdk@latest` and re-run. (2) If it persists, note\n  that the compiled `.ocpkg` is still valid for a current Owncast server (the\n  skew is only in the local test harness), proceed to **Step 5**, and tell the\n  user tests couldn't run locally due to a toolchain version mismatch. Do not\n  loop on it.\n\n(If `npm install` cannot reach the network and the toolchain can't be fetched,\ntell the user that's required once, and continue to write correct code so they\ncan run `npm install && npm test && npm run package` themselves.)\n\n### Step 5: Package and hand off\n\n```sh\nnpm run package\n```\n\n`package` first load-checks the plugin — the same install-time path a real\nOwncast server runs. A handler whose gating permission isn't declared in the\nmanifest (a chat filter without `chat.filter`, a fediverse handler without\n`fediverse.inbound`) aborts packaging with the exact error the server would\ngive at install. Fix the manifest, don't work around the check.\n\nThis produces **`\u003Cslug>.ocpkg`** in the project directory, a single self-contained\nfile bundling the manifest, your plugin source (`\u003Cslug>.js`), and any `public\u002F`\u002F\n`assets\u002F`\u002F`icon.png`\u002F`INSTRUCTIONS.md`. Give the user the path to that file and tell them\nhow to install it:\n\n> Open **Plugins** in your Owncast admin → **Upload plugin** → select\n> `\u003Cslug>.ocpkg`. Then review the **Permissions** tab and toggle **Enabled**.\n> (Alternatively, drop the file into `data\u002Fplugins\u002F` on the server.)\n\nBriefly summarize what the plugin does and which permissions the admin will be\nasked to approve, and why each is needed.\n\n---\n\n## Capability map (intent → handler + API + permission)\n\nMatch the user's described behavior to these rows. Define the listed handler(s),\ncall the listed API, and add the listed permission to the manifest. Several rows\ncombine for richer plugins.\n\n| They want to…                                   | Handler(s)                                   | API call                                  | Permission(s)                          |\n| ----------------------------------------------- | -------------------------------------------- | ----------------------------------------- | -------------------------------------- |\n| React to chat messages                          | `onChatMessage(msg)`                         | —                                         | — (add `chat.send` to reply)           |\n| Reply \u002F post in chat                            | (any handler)                                | `owncast.chat.send(text)` \u002F `.sendAction` | `chat.send`                            |\n| Whisper privately to a sender                   | `onChatMessage`\u002F`filterChatMessage`          | `owncast.chat.replyTo(msg, text)`         | `chat.send`                            |\n| Run chat commands (`!uptime`, etc.)             | `commands: { uptime: { run(ctx) {} } }`      | `ctx.reply` \u002F `ctx.replyPrivately`        | `chat.send` to reply                  |\n| Inspect\u002Fmodify\u002Fdrop every message (moderation)  | `filterChatMessage(msg)`                     | `filter.pass\u002Fmodify\u002Fdrop`                 | `chat.filter` (required for the handler) |\n| Delete a message \u002F kick a client                | (any)                                        | `owncast.chat.deleteMessage` \u002F `.kick`    | `chat.moderate`                        |\n| Read recent chat \u002F list clients                 | (any)                                        | `owncast.chat.history()` \u002F `.clients()`   | `chat.history`                         |\n| React when stream goes live \u002F stops             | `onStreamStarted` \u002F `onStreamStopped`        | —                                         | —                                      |\n| Read live stream state (title, viewers, uptime) | (any)                                        | `owncast.stream.current()`                | `server.read`                          |\n| Read server info \u002F socials \u002F emotes \u002F tags      | (any)                                        | `owncast.server.*()`                      | `server.read`                          |\n| Store per-user or persistent state              | (any)                                        | `owncast.kv.get\u002Fset` (+ `getJSON\u002FsetJSON`)| `storage.kv`                           |\n| Rank or aggregate data (private SQL database)   | (any)                                        | `owncast.sql.exec\u002Fquery\u002FqueryRow`         | `storage.sql`                          |\n| Expose admin-configurable settings              | (read at runtime)                            | `owncast.config.get(key, fallback?)`      | — (declare under `config` in manifest) |\n| Call an external API \u002F webhook                  | (any)                                        | `owncast.http.fetch(url, opts?)`          | `network.fetch` + `network.allowedHosts` |\n| Do delayed \u002F periodic work                      | `onTick({now})` or `owncast.timer.*`         | `owncast.timer.setTimeout\u002FsetInterval`    | — (ambient)                            |\n| Serve a web page \u002F overlay \u002F JSON endpoint      | `onHttpRequest(req)` + files in `public\u002F`    | return `{status, headers, body}`          | `http.serve`                           |\n| Push realtime updates to a browser              | (any)                                        | `owncast.sse.send(channel, event, data)`  | `http.sse`                             |\n| Add an admin settings page in the Owncast UI    | `onHttpRequest` + `public\u002Fadmin\u002F...`         | —                                         | `http.serve` + `admin.pages` manifest  |\n| Add a button under the viewer's stream          | (manifest only, or `owncast.actions.add`)    | —                                         | `ui.modify` (+ `http.serve` if it opens your page) |\n| Inject CSS \u002F JS \u002F HTML into the viewer page     | (manifest `styles`\u002F`scripts`\u002F`extraPageContent`) | dynamic `onPageStyles()` \u002F `onPageScripts()` \u002F `onPageContent({slug,user})` | `ui.modify`                            |\n| Add a tab to the viewer page                    | optional `onTabContent({slug,user})`         | —                                         | `ui.modify` (+ data perms used)        |\n| Upload a file and get a public URL              | (any)                                        | `owncast.storage.upload(name, bytes)`     | `storage.upload`                       |\n| Private server-side files                       | (any)                                        | `owncast.fs.*`                            | `storage.fs`                           |\n| Send Discord \u002F browser-push \u002F fediverse notice  | (any)                                        | `owncast.notifications.*`                 | `notifications.send`                   |\n| Post publicly to the fediverse (high-trust)     | (any)                                        | `owncast.fediverse.post(text)`            | `fediverse.post`                       |\n| React to any verified inbound fediverse activity | `onFediverse(activity)` for raw JSON, plus `onFediverseFollow\u002FLike\u002FRepost\u002FQuote\u002FMention\u002FReply` for specialized payloads | none | `fediverse.inbound` |\n| Read\u002Fchange video\u002Ftranscoding config            | (any)                                        | `owncast.videoConfig.read\u002Fwrite`          | `videoconfig.read` \u002F `videoconfig.write` |\n| Compose with other plugins via custom events    | own local hooks with `on:{}`, emit to `\u003Crecipient-slug>.\u003Chook>` | `owncast.events.emit(type, payload)` | `events.emit` (emitter only) |\n| Gate the site behind a member login (paywall) | `onHttpRequest` (login flow) + `onAuthCheck` (re-validation) | `owncast.users.register` + `owncast.auth.grantSession\u002FendSession` | `auth.gate` + `users.register` (+ `http.serve`); model on `examples\u002Fjs\u002Fgithub-auth` |\n\n**Golden rule:** the `permissions` array must contain exactly the permissions\nrequired by the handlers you register and every `owncast.*` method you call.\nMissing one means the call throws and\u002For the host refuses to load the plugin.\nDon't add permissions you don't use, since admins judge trust by the declared list.\n\n---\n\n## Writing handlers\n\n```js\nconst { definePlugin, owncast, filter } = require(\"@owncast\u002Fplugin-sdk\");\n\nmodule.exports = definePlugin({\n  onChatMessage(msg) {\n    \u002F\u002F msg: { id, user, clientId?, body, timestamp }. msg.user is a ChatUser\n    \u002F\u002F object in production ({id, displayName, scopes?}); older hosts and\n    \u002F\u002F scaffolded test scenarios may send it as a plain display-name string,\n    \u002F\u002F so read the name defensively.\n    const name = typeof msg.user === \"string\" ? msg.user : msg.user?.displayName;\n    if (\u002F^hi\\b\u002Fi.test(msg.body)) {\n      owncast.chat.send(`hello, ${name ?? \"there\"}!`);\n    }\n  },\n});\n```\n\nDefine **only** the handlers you need. The SDK derives event subscriptions from\nwhich handlers exist. Full list of handlers: `onChatMessage`,\n`filterChatMessage`, `onChatUserJoined`, `onChatUserParted`,\n`onChatUserRenamed`, `onMessageModerated`, `onStreamStarted`, `onStreamStopped`,\n`onStreamTitleChanged`, `onFediverse`, `onFediverseFollow\u002FLike\u002FRepost\u002FQuote\u002FMention\u002FReply`,\n`onHttpRequest`, `onTick`, `onSseConnect\u002FDisconnect`, `onTabContent`,\n`onPageContent`, `onPageStyles`, `onPageScripts`, and\n`on: { \"event\"() {} }` for local custom hooks. The host registers each as\n`\u003Cyour-plugin-slug>.event`, which emitters use as the target.\n\nImportant shape\u002Fbehavior notes:\n\n- **`msg.user` is a string *or* an object.** In production it's a `ChatUser`\n  (`{ id, displayName, scopes? }`). Older hosts and the scaffolded test\n  scenarios send a plain display-name string. Read the name defensively:\n  `typeof msg.user === \"string\" ? msg.user : msg.user?.displayName`. For stable\n  per-user state and moderator gating use the object form (`msg.user?.id`,\n  `msg.user?.scopes?.includes(\"MODERATOR\")`), never match on display name, and\n  treat a string or absent user as having no id\u002Fscopes. Declarative command\n  tables handle moderator gating automatically.\n- **Chat text is HTML-escaped on display.** `chat.send`\u002F`sendAction` take plain\n  text. The exception is `chat.system(body)`, whose body renders as HTML, so escape\n  untrusted content yourself.\n- **Filters fail open and are time-capped (50 ms).** `filterChatMessage` must be\n  fast. A filter that errors is treated as `filter.pass()`. Five consecutive\n  failures auto-disable the plugin for the session.\n- **`Date`\u002F`Date.now()` work**, but there is no global `setTimeout`. Use\n  `owncast.timer.*`. Timers don't survive a host restart.\n- **`owncast.sql.*` is one private SQLite database per plugin.** Each `exec` is\n  a single atomic transaction, so a multi-statement schema setup either lands\n  whole or not at all. An unbounded `query` that overruns the host's row or\n  result budget is an error, not a truncated result, so write a `LIMIT`, or use\n  `queryRow` when you only need one row. Plugin databases are not included in\n  Owncast's backups. Worked example: `examples\u002Fjs\u002Fchat-leaderboard`.\n- **Chat commands:** declare a `commands` table in `definePlugin`. Command\n  tables support prefixes, aliases, parsed arguments, moderator gating, and\n  per-user cooldowns. Unknown and gated invocations are silent.\n\n## The manifest\n\n```json\n{\n  \"api\": \"1\",\n  \"name\": \"Welcome Bot\",\n  \"slug\": \"welcome-bot\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Greets people when they join the chat\",\n  \"permissions\": [\"chat.send\"]\n}\n```\n\n- `name`: human-readable, and also the default chat-bot display name. `bot.displayName` overrides it.\n- `slug`: canonical id (URL prefix, storage namespace, filename). Auto-derived from `name` if omitted, but keep it explicit and matching the directory.\n- `permissions`: see the Capability map. Declare exactly what you use.\n- `config`: optional admin-configurable settings: `{ \"key\": { \"type\": \"string|number|boolean\", \"default\": ..., \"description\": \"...\" } }`, read via `owncast.config.get`.\n- UI fields (`actions`, `styles`, `scripts`, `extraPageContent`, `tabs`) all require `ui.modify`.\n- `tabs`: `{ \"tab-slug\": { \"title\": \"Tab label\", \"content\": \"optional.html\" } }`.\n- `admin.pages`: `{ \"\u002Fadmin\u002F*\": { \"title\": \"Settings\" } }`. The host auth-gates matching path keys.\n- **`network.fetch` also requires `network` block:** `\"network\": { \"allowedHosts\": [\"api.example.com\", \"*.weather.com\"] }`. The bare wildcard `\"*\"` is allowed but must be written explicitly. The host rejects the load if `network.fetch` is granted without `allowedHosts`.\n\n## Project layout\n\n```\n\u003Cslug>\u002F\n├── plugin.manifest.json   # identity + permissions\n├── icon.png               # optional: admin-list icon (bundled automatically)\n├── INSTRUCTIONS.md        # optional: rendered as an admin tab\n├── src\u002Fplugin.js          # your code\n├── public\u002F                # optional: served at \u002Fplugins\u002F\u003Cslug>\u002F...\n├── assets\u002F                # optional: host-read for inlined styles\u002Fscripts\u002FHTML (NOT URL-served)\n└── __tests__\u002F*.test.js    # scenario tests\n```\n\n## Testing\n\nReplace the scaffolded test with scenarios for your behavior. Each scenario\ndispatches events and asserts on observed side effects:\n\n```js\nconst { runScenarios } = require(\"@owncast\u002Fplugin-sdk\u002Ftesting\");\n\nrunScenarios([\n  {\n    name: \"greets joining users\",\n    events: [{ event: \"chat.user.joined\", payload: { id: \"u1\", displayName: \"alice\" } }],\n    expect: { chatSends: [\"welcome, alice!\"] },\n  },\n]);\n```\n\nStep types: `event`, `filter` (with `expect: {action, payload?, reason?}`),\n`http` (`{method, path, expect:{status, bodyContains?}}`), `tabContent`,\n`pageContent`, `pageStyles`, `pageScripts`, and `authCheck` (drives\n`onAuthCheck` for `auth.gate` plugins). Final-state assertions include `chatSends`, `chatActions`,\n`chatSystems`, `chatTo`, `sseSends`, `emits`, `kv`, `httpRequests`,\n`videoConfigWrites`. Seed inputs with `given` (`given.kv`, `given.config`,\n`given.stream`, `given.users`, `given.httpResponses`, etc.). Use `authenticated: true` or a\n`user` object on `http` steps to test admin\u002Fuser-gated endpoints.\n\nShapes that trip people up:\n\n- **A chat event's `user` can be a string or an object.** The scaffolded tests\n  use the string shorthand (`payload: { user: \"alice\", ... }`), while production sends\n  a `{ id, displayName, scopes? }` object. Keep your test payloads and handler in\n  sync: if the handler reads `msg.user.id` \u002F `.scopes` (or `.displayName`), pass\n  an object (`user: { id: \"u1\", displayName: \"alice\" }`). If it reads a bare\n  string, pass a string. The defensive read above works with both.\n- **`config` values come from the manifest defaults** unless the scenario seeds\n  admin overrides via `given.config` (`\"given\": { \"config\": { \"key\": \"value\" } }`).\n  `owncast.config.get(\"key\")` returns the override when seeded, otherwise the\n  `default` declared under `config` in `plugin.manifest.json`. Test both paths.\n- **One `given.httpResponses` entry per URL pattern.** The `url` is a glob\n  matched against the full URL (`\"https:\u002F\u002Fapi.example.com\u002Fuser*\"` covers any\n  query string) and the first match wins, so a sequence where the same URL must\n  answer differently across calls can't be modeled by fixtures.\n\nFor interactive iteration, `npm run serve` hosts the plugin on\n`http:\u002F\u002Flocalhost:8080\u002Fplugins\u002F\u003Cslug>\u002F` with `\u002F_dev\u002F*` endpoints to fire events.\n\n## Common recipes (copy and adapt)\n\n**Greeter** (`permissions: [\"chat.send\"]`):\n```js\nmodule.exports = definePlugin({\n  onChatUserJoined(user) { owncast.chat.send(`welcome, ${user.displayName}!`); },\n});\n```\n\n**Word filter** (`permissions: [\"chat.filter\"]`):\n```js\nmodule.exports = definePlugin({\n  filterChatMessage(msg) {\n    return \u002Fbadword\u002Fi.test(msg.body) ? filter.drop(\"blocked\") : filter.pass();\n  },\n});\n```\n\n**External fetch on command** (`permissions: [\"chat.send\",\"network.fetch\"]`, `network.allowedHosts: [\"api.ipify.org\"]`):\n```js\nmodule.exports = definePlugin({\n  onChatMessage(msg) {\n    if (msg.body.trim() !== \"!ip\") return;\n    const res = owncast.http.fetch(\"https:\u002F\u002Fapi.ipify.org?format=json\");\n    if (res.status === 200) owncast.chat.send(`IP: ${JSON.parse(res.body).ip}`);\n  },\n});\n```\n\n**Notify Discord on stream start** (`permissions: [\"notifications.send\"]`):\n```js\nmodule.exports = definePlugin({\n  onStreamStarted(info) { owncast.notifications.discord(`Live now: ${info.title || \"stream\"}`); },\n});\n```\n\n## Where to go deeper\n\nThe repository's `docs\u002FPLUGIN_AUTHOR_GUIDE.md` is the exhaustive reference\n(every handler, every API method, limits, SSE, admin pages, action buttons,\nviewer-page injection, full testing model). Read it when a request needs a\nfeature this summary only outlines. Worked examples live in `examples\u002Fjs\u002F`.\n\nThe public documentation at \u003Chttps:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins> covers the same\nground for authors who want a web reference: the\n[JavaScript SDK](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fsdks\u002Fjavascript),\n[Manifest](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fmanifest),\n[Events](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fevents),\n[Owncast APIs](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fapis),\n[Permissions](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpermissions),\n[Testing](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Ftesting), and\n[Packaging](https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins\u002Fpackaging) pages.\n\n## Checklist before you hand off the .ocpkg\n\n- [ ] `name`, `slug`, real `description` set (not the `\"An Owncast plugin\"` placeholder), and slug valid and matches the directory.\n- [ ] `permissions` lists exactly the APIs the code calls, no more and no less.\n- [ ] `network.allowedHosts` present if `network.fetch` is used, `ui.modify` present for any UI field, and `chat.filter` present if `filterChatMessage` is defined.\n- [ ] `INSTRUCTIONS.md` is written for the person installing\u002Frunning the plugin (what it does and how to use it once enabled), not the scaffold placeholder, and it ships in the `.ocpkg`.\n- [ ] `npm test` passes, or, if it failed only on a toolchain\u002Fversion skew (not your logic), you confirmed that and said so.\n- [ ] `npm run package` produced `\u003Cslug>.ocpkg`, you gave the user its path and install instructions, and noted which permissions the admin must approve.\n",{"name":5,"description":7},"main","3928e52173698bd34afb9e360f500b1553d8dd2f","sdks\u002Fjs\u002Fcreate-owncast-plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-js",0,"https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk","https:\u002F\u002Fowncast.online\u002Fdocs\u002Fplugins","https:\u002F\u002Fgithub.com\u002Fowncast","http:\u002F\u002Fowncast.online","A self-hosted live stream server with chat features.","2026-10-11 08:19:38",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add owncast\u002Fplugin-sdk --skill create-owncast-plugin-js",{"tool":40,"command":41},"bunx","bunx skills add owncast\u002Fplugin-sdk --skill create-owncast-plugin-js",{"tool":43,"command":44},"pnpm","pnpm dlx skills add owncast\u002Fplugin-sdk --skill create-owncast-plugin-js","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002Fsdks\u002Fjs\u002Fcreate-owncast-plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-js\u002FSKILL.md",true,[],[49,56,63,68],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M734FNTE1T55VXFF71KBTZP3","create-owncast-plugin-py","Build a complete Owncast plugin in Python from a plain-language description and hand back an installable .ocpkg file. Use when someone wants to create, build, scaffold, or make an Owncast plugin in Python (a chat bot, chat filter\u002Fmoderation tool, stream-event responder, HTTP page\u002Foverlay\u002Fwidget, admin page, fediverse integration, etc.) without needing to know the SDK internals. If the author hasn't picked a language yet, start from create-owncast-plugin (the router) instead.","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002Fsdks\u002Fpython\u002Fowncast_plugin\u002Ftemplate\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-py\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M734F94NDEWJNF2M4C9EHZZE","create-owncast-plugin","Use this skill whenever someone wants to create, build, scaffold, or set up an Owncast plugin, or just describes new behavior they want in their Owncast chat or server without naming it a 'plugin.' This is the entry point for any new plugin, in any language: a chat bot or auto-responder, a welcome greeter, a word\u002Flink filter or moderation action, a moderator button or admin page, a stream-going-live reaction, a fediverse follow\u002Fpost integration, or a live web overlay or widget (viewer count, chat feed). Casual asks count fully: 'I run an Owncast server and want a bot that…', 'make me something that auto-replies when…', 'add a button so mods can…'. It captures the desired behavior, settles on JavaScript or Python, then hands off to the matching language skill. Skip it only when the language is already chosen (use the JavaScript or Python skill directly), and for general Owncast streaming\u002Finstall\u002Fconfig help or bots on other platforms like Twitch or Discord.","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin\u002FSKILL.md",[],[],{"skillNo":64,"name":51,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M734F6S9P0AF9JW577FZTPWD","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-py\u002FSKILL.md",[],[],{"skillNo":69,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M734F4E68J3R8H7PJFN82EMY","https:\u002F\u002Fgithub.com\u002Fowncast\u002Fplugin-sdk\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcreate-owncast-plugin-js\u002FSKILL.md",[],[]]