Skip to main content
Kalam Documentation

Your first plugin

A plugin is a folder with kalam-plugin.json and a worker script. This walkthrough saves a note when a take starts with note to self, and types nothing into the focused app.

You need Kalam running on this computer, and node on PATH. The host launches Node workers with the node executable.

1. Create the folder​

Plugins live in <Kalam config>/plugins/<folder>/. The config directory is ~/.kalam (Windows: %USERPROFILE%\.kalam), unless you opened Labs and copied the path from Plugins directory.

Create ~/.kalam/plugins/note-to-self/.

2. Write the manifest​

Save this as kalam-plugin.json in that folder.

{
"schema_version": 1,
"id": "com.example.note-to-self",
"name": "Note to self",
"version": "0.1.0",
"description": "Turns “note to self …” into a Kalam note.",
"platforms": ["windows", "macos", "linux"],
"entrypoints": {
"backend": { "runtime": "node", "command": "bin/worker.mjs" }
},
"permissions": [
"dictation:intercept",
"entries:write",
"process:spawn"
],
"interceptors": [
{
"id": "note-to-self",
"stage": "before_inject",
"priority": 40,
"match": {
"kind": "prefix_or_keyword",
"prefixes": ["note to self"],
"keywords": []
},
"timeout_ms": 1500
}
]
}

process:spawn is required because the manifest declares a backend. dictation:intercept is required because it declares an interceptor. entries:write is required for entries.create.

The id may contain ASCII letters, digits, ., -, and _. It cannot start or end with ., and it cannot contain ... version is a semantic version. command is a relative path inside the plugin folder.

3. Set up package.json and the worker​

Ensure Node resolves ES modules and @kalam/plugin-sdk inside your plugin folder. @kalam/plugin-sdk (0.1.0) is bundled in the Kalam desktop repository under packages/plugin-sdk (not yet published to the public npm registry), so point a file: dependency at your local checkout—or speak the newline-delimited JSON-RPC 2.0 protocol directly on stdin/stdout.

Save package.json inside ~/.kalam/plugins/note-to-self/:

{
"name": "kalam-plugin-note-to-self",
"version": "0.1.0",
"private": true,
"type": "module",
"dependencies": {
"@kalam/plugin-sdk": "file:/path/to/kalam/packages/plugin-sdk"
}
}

Then run npm install (or pnpm install) inside that plugin directory, and save bin/worker.mjs:

import { definePlugin, divert, pass } from '@kalam/plugin-sdk'

definePlugin({
async onIntercept(ctx, host) {
const raw = ctx.text.trim()
const prefix = 'note to self'
if (!raw.toLowerCase().startsWith(prefix)) return pass()
const content = raw.slice(prefix.length).trim()
if (!content) return pass()
await host.call('entries.create', {
entry_type: 'note',
title: 'Note to self',
content,
})
return divert('Saved note')
},
})

pass() leaves the take alone. divert('Saved note') consumes it. The status text is what Kalam can show; the words are not typed into the other app.

The host only calls kalam.intercept after the manifest rule matches. Still check the text. Another plugin can transform the string before you see it.

4. Enable it​

  1. Open Labs.
  2. Turn on Plugin platform.
  3. Turn on Developer mode while you are editing files.
  4. Choose Refresh if the folder is new.
  5. Turn on Note to self. The manifest line should read Ready.

If it reads Needs attention, open the plugin and read the manifest error. A backend without process:spawn, or an interceptor without dictation:intercept, is rejected.

5. Try it​

Focus another app. Hold your dictation key, say note to self buy milk, and release. The take should not land in that app. A note titled Note to self should appear under Notes.

Change the script, then choose Restart on the plugin. Kalam does not reload a running worker by itself.

What to add next​

GoalRead
Settings fields in LabsManifest config_schema
A chip on the PillHost methods pill.setSlot
A sidebar pageSDK WebView, and ui:view
A spoken command that is not an interceptorCommand actions plugin_action