Skip to main content
Kalam Documentation

Best practices

Ask for the smallest permission list that still does the job. A plugin that only stamps text needs dictation:intercept and process:spawn. It does not need the clipboard, the browser URL, or llm:invoke.

Stay off the sensitive path​

The host already blanks titles and transcripts for a sensitive foreground app, and it refuses context reads, language-model calls, and plugin_action commands there. Do not keep your own copy of a transcript "just in case." Do not write raw_text or final_text to a log line. Diagnostics in Labs shows recent worker output on this computer. Treat that stream as something the person can read.

If focus.sensitive is true, skip the take.

Interceptors have a budget​

The default timeout is 250 milliseconds. The host stops waiting when you exceed timeout_ms. A handler that calls llm.structured needs a higher timeout, and uses_llm: true on that interceptor.

Prefer before_inject when you need the polished sentence. Prefer before_polish only when the model should see your change.

Return pass() for everything you do not own. match.kind of all runs on every take. Keep that function to a prefix check and a return.

priority is ascending. 40 runs before 100. Do not depend on another plugin's id for order.

divert means the words never reach the focused app. Set status_message so the Pill can say what happened.

Hooks are not a second pipeline​

Subscribe with dictation:observe when you need the finished fact. Do not also intercept every take to learn that it finished. dictation.heard can fire many times for one take. Join on take, and ignore partial text after dictation.final or dictation.delivered for that id.

onHook has no return channel. A slow hook must not block the next line on stdin. The SDK starts the handler and does not await it before reading the next message. Still avoid unbounded work.

Storage stays in the plugin folder​

storage.kv.* and storage.sql.* open <plugin folder>/data/plugin.db. The connection rejects ATTACH, DETACH, load_extension, and most PRAGMA statements. A query returns at most 1000 rows. Do not try to open Kalam's own database. Notes, tasks, and reminders go through entries.*, which checks entries:read or entries:write.

Do not put secrets in config_schema defaults. Those defaults ship inside the folder.

Pill and views​

pill.setSlot keeps 24 characters of text. Longer strings are cut. Declare the slot id in pill_slots first.

A full Pill skin (pill:replace) is a Windows and macOS overlay. Linux keeps the panel chip. Use pill:slot when the plugin should show a chip on all three.

Post kalam:webview:ready as soon as the page loads. The skin helper in the SDK does this. A skin that stays silent is treated as not ready.

pill.control only works while that plugin is the active skin. Read state with get_state or list_modes before you change the mode.

Workers​

Restart the worker from Labs after you edit the script. A crash loop shows Stopped after error and the last lines under Diagnostics.

activation_events of onHook:… keeps the process down until that hook fires. An empty list starts it when the plugin is enabled. Pick the lazy form for a plugin that only cares about one event.

Node and Python runtimes use whatever node or python is on PATH. Document that requirement next to your install steps. Kalam does not vendor a runtime.

Commands versus interceptors​

If the person must say a phrase, add a command with plugin_action and return { "text" } or { "status_message" }. If every matching take should change with no extra phrase, use an interceptor. Doing both for the same prefix surprises people: the command and the interceptor can both claim the words.

Test the sensitive-app case, an empty remainder (note to self with nothing after it), and a timeout. Those three fail closed. The take should still have an obvious outcome.

Pre-flight checklist​

CheckRequirement
Minimal permissionsRequest only capabilities actually invoked (dictation:intercept vs dictation:observe, storage:local, etc.).
Sensitive windowsNever log raw_text / final_text; check focus.sensitive before processing.
Timeout budgetKeep non-LLM interceptors well under 250 ms (timeout_ms) and set uses_llm: true when calling llm.*.
Storage hygieneUse storage.kv.* / storage.sql.* (with bound params) or entries.*; keep secrets out of config_schema defaults.
Pill & WebViewKeep slot labels ≤ 24 chars and call createKalamWebviewClient() immediately at load for custom skins.
Trigger clarityDo not attach both a Command (plugin_action) and an Interceptor to the exact same spoken prefix.