Skip to main content
Kalam Documentation

Plugin platform

A Kalam plugin is a folder on this computer. Kalam starts its worker, sends it facts about dictation, and answers only the host methods its manifest allows. The worker never receives an API key.

This page explains the model. To build one, follow Your first plugin. The call list is Host methods.

Three ways to extend a take​

MechanismWho starts itWhat it can do
Command (plugin_action)The speaker, by a trigger phrase on the Commands pageRun a built-in action, or call one method on an enabled plugin. (Distinct from inline Dictation voice commands like period or scratch that.)
InterceptorKalam, when the dictated text matches a rule in kalam-plugin.jsonLeave the text, replace it, or consume the take so it is not typed
HookKalam, after something already happenedObserve. A hook does not return a decision

Use a Command (plugin_action) when the speaker invokes an action out loud. Use an Interceptor when every matching take should change before it is polished or typed. Use a Hook when you only need to observe finished takes or focus changes.

What runs where​

The worker is a separate process. It talks newline-delimited JSON-RPC 2.0 on stdin and stdout. A sidebar or Pill page is a sandboxed web view. It cannot call Tauri directly. It posts messages through the bridge in SDK.

What you turn on​

In Labs:

  1. Plugin platform must be on. Host calls fail while it is off.
  2. The plugin must be turned on in Your plugins.
  3. Developer mode shows the folder, manifest status, and recent worker output. Use it while you build.

The reference suite on that page is five plugins shipped with the app: spoken tasks, window focus, a Pill timer, a voice-pace badge, and a text stamp. They are examples of this same contract.

Trust boundary​

Permissions are an allow list in kalam-plugin.json. The host checks the list before it delivers a hook or runs a method. A missing permission returns JSON-RPC code -32001.

These calls also refuse while the foreground app is marked sensitive, and return -32002:

  • context.selection, context.clipboard, context.url
  • llm.complete, llm.structured
  • a voice command whose action is plugin_action

Sensitive focus snapshots keep the process name and clear the window title. dictation.delivered omits raw_text and final_text for that take.

config.get, engine.current, and engine-change hooks do not require a permission. Engine snapshots never include an API key.