AI Agent Build Guide

Written for an AI coding agent building a Kunkun extension — but readable by anyone; it's the whole flow on one page. Point your agent at the raw Markdown: https://docs.kunkun.sh/instruction.md. The agent reads the linked docs on demand, so this stays short and never goes stale.

You are helping a developer build a Kunkun extension. Kunkun is an open-source, cross-platform app launcher (an Alfred / Raycast alternative). An extension is an npm package with a kunkun field in its package.json (the "manifest") and one or more commands. Work through this guide in order.

0. Set up

Install the Kunkun skill — deeper, step-by-step guidance for your agent:

npx skills install kunkunsh/kunkun

This installs the kunkun-plugin-development and kunkun-extension-testing skills. You may need to reload or restart your editor/agent before they load. Verify the skill is available before continuing (list your skills). If it loaded, prefer following it — it is more detailed than this file and ships reference material and worked examples.

Read the docs on demand — do not guess APIs:

• Docs index (all pages): https://docs.kunkun.sh/llms.txt
• Any page as Markdown: https://docs.kunkun.sh/llms.mdx/docs/<path> (paths are in the map below)
• Everything in one file: https://docs.kunkun.sh/llms-full.txt

For framework/library docs (React, Svelte, Vue, Vite), use Context7 or the library's own docs.

1. Decide what to build (ask the user)

The user may not know Kunkun — or may not have a programming background. Explain each trade-off and recommend a default. Ask these questions, then choose ONE command mode.

Q1 — Does the command need a visible UI?

• No → a headless command. Ask how it runs: on demand, on a schedule (interval / cron), or on an event. Pick a runtime: worker-headless (sandboxed, no system access) or node-headless (Node/Deno — filesystem, shell, network, native modules). → Read Headless Commands.
• Yes → go to Q2.

Q2 — How complex is the UI?

• Simple / standard (a searchable list, a form, a detail pane — Raycast-style) → worker-view. A React component the host renders through Uniview primitives: consistent styling, strong isolation, no direct DOM. System access (fs, shell, dialogs) is still available through the permission-gated host API — declare what you use in the manifest. This is the best default for most UI extensions. → Read Worker Extension.
• Complex / fully custom (charts, canvas, drag-and-drop, a data/DB visualizer, a whole SPA, or a specific framework) → custom-view. Your own single-page app in an isolated window — full control of the DOM and dependencies. → Read Custom UI Extension.
• Needs the Node runtime itself (Node built-ins, native .node addons, heavy CPU work) AND a React UI → node-view (same React UI on a Node/Deno process). Plain fs/shell calls do NOT require this — worker-view covers them via the host API. → Read the worker guide above, plus Backend Processes.

Q3 — (custom-view only) Which stack? Svelte, React, Vue, or vanilla — any static-SPA framework works with Vite. Ask the user's preference.

Q4 — Persistent backend, heavy compute, or native .node addons? If yes, add a backend process (spawnBackend) or use a node-headless runtime. → Read Backend Processes.

Q5 — Store data? A few flags → LocalStorage (key/value). A list of records with queries, search, or pagination → record storage (db.collection). → Read Record Storage.

Q6 — Call, or expose functionality to, other extensions? Use services (contract-first, typed). → Read Services.

Always: every capability the extension uses must be declared in the manifest permissions. → Read Permissions and the Manifest Reference (has an interactive validator).

If the user is unsure, default to worker-view for anything with a simple UI, node-headless for a background task, and only reach for custom-view when the UI genuinely needs a custom framework or direct DOM.

2. Scaffold and implement

1. Read Getting Started for exact commands.
2. Scaffold:
   • custom-view: npm create vite@latest (pick the framework), disable SSR / emit a static build, then pnpm add @kunkunsh/sdk.
   • worker-view / node-view / headless: a minimal package plus a one-line build.ts using @kunkunsh/sdk/build (Bun). pnpm add @kunkunsh/sdk (and react for views).
3. Write the kunkun manifest in package.json: a stable reverse-DNS identifier, name, icon, permissions, and a commands entry with the chosen mode and its main entry point.
4. Implement with @kunkunsh/sdk (host APIs: clipboard, fs, shell, dialog, network, db, …) and, for worker/node views, @kunkunsh/sdk/ui components. Reference the SDK API Reference.
5. Load & test: in Kunkun, Settings → Developer → Load Extension. For headless/service extensions, use the test harness (see the kunkun-extension-testing skill).
6. Publish when ready.

Doc map

Each path below is https://docs.kunkun.sh/llms.mdx/docs/<path>.

Rules

• Never invent APIs, permission names, or manifest fields — ground everything in the docs above.
• Validate the manifest against the schema (the Manifest Reference page has a live validator).
• Extensions install as built artifacts: the build must be self-contained (bundle JS deps).
• Prefer worker-view unless the UI truly needs custom-view.