Kunkun Docs

Your extension's manifest is the kunkun field of its package.json. It's validated by a Valibot schema shipped in @kunkunsh/sdk/manifest — the same schema powers the validator below.

Interactive validator

Paste or edit a package.json and it's checked live against the real schema:

Manifest validator● valid

This validates the whole package.json (the top-level fields plus kunkun). Errors show the field path and message.

Top-level `package.json`

Field	Type	Notes
`name`	string	npm package name (required)
`version`	string	semver (required)
`license`	string	required
`$schema`	string	`https://schema.kunkun.sh/` for editor hints
`author`, `contributors`, `repository`, `description`	—	standard npm fields
`files`	string[]	what ships in the tarball (e.g. `["dist"]`)
`kunkun`	object	the manifest (below)

`kunkun` manifest

Field	Type	Notes
`identifier`	string	Required. Stable, unique id (e.g. `com.you.tool`). Keys installs, storage, grants — never change it.
`name`	string	Display name (falls back to package name)
`shortDescription` / `longDescription`	string	Store listing
`icon`	Icon	see below
`commands`	Command[]	Required. One entry per command
`permissions`	Permission[]	see Permissions
`preferences`	Preference[]	extension-wide preferences
`demoImages`	string[]	screenshots for the store
`categories`	Category[]	store categories
`platforms`	("linux"\|"macos"\|"windows")[]	restrict to platforms
`services`	Service[]	exposed services
`serviceDependencies`	ServiceDependency[]	services you consume
`bindings`	object	host LLM/resource bindings
`binaryDependencies`	BinaryDependency[]	host-managed binaries

Icon

{ "type": "iconify", "value": "mdi:puzzle", "invert": true }

type: "iconify" uses an Iconify id; invert flips for dark mode.

Command

Field	Type	Notes
`name`	string	internal command id
`title`	string	shown in the palette
`description`	string	—
`mode`	CommandMode	see below
`main`	string	entry: route (`/`), `dist/App.js`, or `dist/node/App.js`
`dist`	string	build output dir (custom-view)
`devMain`	string	dev server URL (HMR)
`icon`	Icon	per-command icon
`window`	WindowConfig	custom-/node-view window options
`runtime`	`"auto"\|"deno"\|"node"`	Node-mode runtime override
`interval`	number \| `"5m"`	schedule (headless)
`cron`	string	cron schedule (headless)
`arguments`	Argument[]	user inputs
`preferences`	Preference[]	per-command preferences
`keywords`	string[]	extra search terms
`platforms`	OSPlatform[]	restrict this command

mode — one of:

Value	Runtime	Notes
`custom-view`	BrowserWindow	your own SPA
`worker-view`	Web Worker	React via Uniview
`node-view`	Node/Deno	React + system access
`worker-headless`	Web Worker	no UI
`node-headless`	Node/Deno	no UI + system access
`menu-bar`	Tray	menu-bar command
`quicklink`	—	navigate to a `link`
`view` / `no-view`	—	Raycast aliases → `node-view` / `node-headless`

Window config (custom-/node-view)

{ "titleBarStyle": "overlay", "transparent": true, "vibrancy": "sidebar", "width": 700, "height": 550 }

Service

{
  "name": "math",
  "description": "Math operations",
  "main": "dist/node/MathService.js",
  "serviceMode": "node-headless",
  "methods": [
    { "name": "add", "description": "Add", "inputSchema": { /* JSON Schema */ }, "outputSchema": { /* JSON Schema */ } }
  ]
}

See Services for the full pattern.

Permissions

Simple strings or scoped objects — the complete catalogue and scope shapes are in Permissions. Quick shape reminder:

{
  "permissions": [
    "clipboard-read",
    { "permission": "fs-read", "allow": ["$EXTENSION_SUPPORT/**"] },
    { "permission": "network", "domains": ["*.github.com"] },
    { "permission": "shell", "commands": [{ "program": "git", "args": ["status"] }] },
    { "permission": "backend", "allow": [{ "script": "$EXTENSION/dist/backend.js", "runtime": "node" }] }
  ]
}

Minimal valid manifest

{
  "name": "hello",
  "version": "0.1.0",
  "license": "MIT",
  "kunkun": {
    "identifier": "com.you.hello",
    "commands": [{ "name": "main", "title": "Hello", "mode": "worker-view", "main": "dist/App.js" }]
  }
}

Manifest Reference