Manifest reference
kalam-plugin.json is the plugin contract. Kalam rejects the folder when validation fails. Schema version is 1 (schema_version).
Required fields
| Field | Rule |
|---|---|
id | ASCII letters, digits, ., -, _. Length 1–96. No leading or trailing .. No ... |
name | Non-empty display name. |
version | Semantic version, such as 0.1.0. |
Optional fields
| Field | Default | Meaning |
|---|---|---|
schema_version | 1 | Must be 1. |
author | omitted | Shown as by … in Labs. |
description | "" | One line in Labs. |
min_kalam_version | omitted | Semantic version. Invalid text fails validation. |
platforms | windows, macos, linux | Where the plugin claims to run. |
entrypoints | none | Worker and views. See below. |
activation_events | empty | When a worker may start. See below. |
permissions | empty | Allow list. Unknown names fail JSON parsing. |
interceptors | empty | Pipeline rules. Requires dictation:intercept. |
pill_slots | empty | Chips the worker may fill. |
net_allowlist | empty | Origins a WebView may use when the plugin has net:http. |
config_schema | omitted | JSON Schema object. Labs renders properties as settings. |
Entrypoints
{
"entrypoints": {
"backend": { "runtime": "node", "command": "bin/worker.mjs", "args": [] },
"main_view": {
"kind": "webview",
"title": "Notes",
"icon": "ph:note",
"entry": "index.html"
},
"pill_view": { "entry": "pill.html" }
}
}
| Entrypoint | Requires | Rule |
|---|---|---|
backend | process:spawn | runtime is node, python, binary, or command. command is one relative path, or a map of windows / macos / linux to a relative path. binary, node, and python paths cannot be absolute and cannot contain ... |
main_view | ui:view | kind is openui or webview. webview needs entry, a file under the plugin UI folder. |
pill_view | pill:replace | entry is the HTML file for a full Pill skin. |
node and python must be on PATH. Kalam runs node <script> or the Python interpreter with the script path. It does not install a runtime for you.
Permissions
Declare only what the plugin calls.
| Permission | Unlocks |
|---|---|
focus:read | focus.changed, focus.sensitive, focus.current |
idle:read | system.idle_changed, system.idle |
dictation:observe | dictation.* hooks |
dictation:intercept | before_polish and before_inject |
context:selection | context.selection |
context:clipboard | context.clipboard |
context:url | context.url |
insert:text | insert.text |
llm:invoke | llm.complete, llm.structured |
entries:read | entries.query |
entries:write | entries.create, entries.update, entries.delete |
storage:local | storage.kv.*, storage.sql.* |
ui:view | ui.renderOpenUI; also one of the permissions accepted by ui.emit |
pill:slot | pill.setSlot, pill.clearSlot, pill.notify, pill.slot_clicked |
pill:replace | pill.setHitRect, pill.control, pill.notify |
net:http | WebView network limited to net_allowlist |
process:spawn | Required to declare entrypoints.backend. It is not a method that runs arbitrary programs. |
ui.emit is allowed when the plugin has ui:view, pill:slot, or pill:replace.
stt.changed, llm.changed, and profile.changed are delivered with no extra permission. They carry no API key.
Activation events
The host starts a backend worker in these cases:
activation_events | When the worker starts |
|---|---|
omitted or [] | When the plugin is enabled |
* or onStartup | When the plugin is enabled |
onHook:<event> | When that hook is published, if the plugin may receive it |
onHook:* | When any hook is published |
An interceptor call and a plugin_action command automatically wake an enabled, healthy worker. Only onStartup / *, onHook:<event>, and onHook:* are supported under activation_events—declarative prefixes like onCommand:* or onIntercept:* are ignored by the supervisor.
Interceptors
{
"id": "capture-task",
"stage": "before_inject",
"priority": 40,
"match": {
"kind": "prefix_or_keyword",
"prefixes": ["new task"],
"keywords": ["remind me"]
},
"uses_llm": false,
"timeout_ms": 1500
}
| Field | Default | Meaning |
|---|---|---|
id | required | Sent to the worker as interceptor_id. |
stage | required | before_polish or before_inject. |
priority | 100 | Lower numbers run first. Ties break by plugin id, then interceptor id. |
match.kind | required | prefix_or_keyword or all. |
match.prefixes | [] | Case-insensitive start of the text. |
match.keywords | [] | Case-insensitive substrings. |
uses_llm | false | Tells the host this handler may call the language model. |
timeout_ms | 250 | The host stops waiting after this many milliseconds. |
match.kind of all runs on every take at that stage. Keep that handler short.
Pill slots
{ "id": "tasks-badge", "position": "trailing", "tooltip": "Open Tasks", "label": "Tasks" }
position is leading or trailing (default trailing). label is the Labs description. The live chip text comes from pill.setSlot, and it is capped at 24 characters. pill.setSlot rejects a slot_id that is not in this list when the list is non-empty.
Settings schema
config_schema is a JSON Schema object. Labs shows each property's title, description, default, and enum. config.get returns those defaults merged with the values the person saved. Saving in Labs sends kalam.config_changed to the worker.