Skip to main content
Kalam Documentation

Manifest reference

kalam-plugin.json is the plugin contract. Kalam rejects the folder when validation fails. Schema version is 1 (schema_version).

Required fields​

FieldRule
idASCII letters, digits, ., -, _. Length 1–96. No leading or trailing .. No ...
nameNon-empty display name.
versionSemantic version, such as 0.1.0.

Optional fields​

FieldDefaultMeaning
schema_version1Must be 1.
authoromittedShown as by … in Labs.
description""One line in Labs.
min_kalam_versionomittedSemantic version. Invalid text fails validation.
platformswindows, macos, linuxWhere the plugin claims to run.
entrypointsnoneWorker and views. See below.
activation_eventsemptyWhen a worker may start. See below.
permissionsemptyAllow list. Unknown names fail JSON parsing.
interceptorsemptyPipeline rules. Requires dictation:intercept.
pill_slotsemptyChips the worker may fill.
net_allowlistemptyOrigins a WebView may use when the plugin has net:http.
config_schemaomittedJSON 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" }
}
}
EntrypointRequiresRule
backendprocess:spawnruntime 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_viewui:viewkind is openui or webview. webview needs entry, a file under the plugin UI folder.
pill_viewpill:replaceentry 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.

PermissionUnlocks
focus:readfocus.changed, focus.sensitive, focus.current
idle:readsystem.idle_changed, system.idle
dictation:observedictation.* hooks
dictation:interceptbefore_polish and before_inject
context:selectioncontext.selection
context:clipboardcontext.clipboard
context:urlcontext.url
insert:textinsert.text
llm:invokellm.complete, llm.structured
entries:readentries.query
entries:writeentries.create, entries.update, entries.delete
storage:localstorage.kv.*, storage.sql.*
ui:viewui.renderOpenUI; also one of the permissions accepted by ui.emit
pill:slotpill.setSlot, pill.clearSlot, pill.notify, pill.slot_clicked
pill:replacepill.setHitRect, pill.control, pill.notify
net:httpWebView network limited to net_allowlist
process:spawnRequired 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_eventsWhen the worker starts
omitted or []When the plugin is enabled
* or onStartupWhen the plugin is enabled
onHook:<event>When that hook is published, if the plugin may receive it
onHook:*When any hook is published
Supported activation events

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
}
FieldDefaultMeaning
idrequiredSent to the worker as interceptor_id.
stagerequiredbefore_polish or before_inject.
priority100Lower numbers run first. Ties break by plugin id, then interceptor id.
match.kindrequiredprefix_or_keyword or all.
match.prefixes[]Case-insensitive start of the text.
match.keywords[]Case-insensitive substrings.
uses_llmfalseTells the host this handler may call the language model.
timeout_ms250The 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.