SDK reference

Import everything from freestyle-voice.

import {
  transform, OutputMode, FreestyleEventType, PipelineStage,
  type Plugin, type PluginContext, type PluginOptions,
  type FreestyleEvent, type AppContext, type HookApi,
  type PluginLlm, type CleanupToneDestination,
} from "freestyle-voice";

Plugin

The object your factory returns. The default export is (options?: PluginOptions) => Plugin | Plugin[] | false | null | undefined. Return an array to ship a preset of plugins, or a falsy value to disable based on options.

interface Plugin {
  name: string;                       // required, stable identifier
  enforce?: "pre" | "post";           // run first or last across all hooks
  setup?: (ctx: PluginContext) => void | Promise<void>;
  dispose?: () => void | Promise<void>;
  middleware?: MiddlewareHandler[];   // Hono handlers (server)
  // plus any of the hooks below
}

Hooks

Each hook is optional. Mutating hooks receive three arguments: a read-only input, an output you change in place, and a HookApi (api) for cancellation/suppression control and — on server hooks — the host’s LLM. They chain across plugins in resolved order (enforce: "pre" → none → "post", then load order).

Hook	Runs	Do
`setup(ctx)`	on load	read settings, init state
`dispose()`	on unload	clean up
`beforeTranscribe(input, output, api)`	before speech-to-text [server]	preprocess `output.audio`, override `output.providerId`/`modelId`/`language`/`bias`, or `api.control.consume()` to skip STT
`afterTranscribe(input, output, api)`	after speech-to-text [server]	rewrite `output.text`, or `api.control.consume()` to skip cleanup + delivery
`beforeCleanup(input, output, api)`	building the AI prompt [server]	push to `output.system`, set `output.destination`, `output.prompt`, or `output.skip`
`afterCleanup(input, output, api)`	after cleanup + dictionary [server]	rewrite `output.text`
`beforeOutput(input, output, api)`	before delivery [app]	rewrite `output.text`, set `output.mode` (no `api.llm` here)
`event({ event })`	throughout [both]	observe only, no mutation
`config(existing)`	boot [server]	return partial config to deep-merge

Hook inputs:

beforeTranscribe → { providerId, modelId, audioDurationMs, appContext? }
afterTranscribe → { providerId, modelId, appContext? }
beforeCleanup → { text, appContext?, destination }
afterCleanup and beforeOutput → { appContext? }

beforeCleanup’s destination is a CleanupToneDestination — "overall" | "personal" | "work" | "email" — the tone bucket the host inferred; set output.destination to override it.

beforeOutput(input, output) {
  if (output.text.startsWith("!")) {
    output.text = "";
    output.mode = OutputMode.None; // eat it as a command
  }
}

Consuming an utterance

A plugin can handle an utterance entirely instead of dictating it — for example, a voice command that ran an action. Call api.control.consume() from a server hook (typically afterTranscribe): the host skips every remaining stage and delivers nothing to the focused app.

afterTranscribe(input, output, api) {
  if (isCommand(output.text)) {
    runCommand(output.text);
    api.control.consume("ran a voice command"); // no cleanup, no output
  }
}

api.control.consume() replaces the old output.consumed flag. It is unambiguous (a genuinely empty transcript is different from a consumed one) and preserves the raw text for logging.

HookApi

The third argument to every mutating hook. Built once per dictation and threaded through every stage, so control and llm are consistent across the whole run.

interface HookApi {
  control: PipelineControl;  // cancellation + suppression for this dictation
  signal: AbortSignal;       // alias for control.signal
  llm?: PluginLlm;           // [server hooks only] the host's LLM, when configured
}

class PipelineControl {
  readonly state: "running" | "consumed" | "aborted";
  readonly reason: string | undefined;
  readonly signal: AbortSignal;
  stopPropagation(): void;   // stop later plugins for THIS hook only
  consume(reason?: string): void; // handled: skip the rest of the pipeline, deliver nothing
  abort(reason?: string): void;   // hard-stop: deliver nothing, emit a pipelineError event
}

stopPropagation() — stop running the remaining plugins for the current hook only; later hooks still run.
consume(reason?) — the utterance is handled (e.g. a voice command). Every remaining stage is skipped and no output is delivered.
abort(reason?) — unrecoverable failure: nothing is delivered and the host emits a pipelineError event. Aborting also fires control.signal, so pass api.signal to cancellable work (e.g. api.llm.generateText({ signal: api.signal })).

The host checks control.state between stages. llm is present only on server hooks (beforeTranscribe, afterTranscribe, beforeCleanup, afterCleanup) and only when an LLM is configured — never on beforeOutput. Always guard with if (api.llm).

PluginContext

Passed to setup.

interface PluginContext {
  name: string;
  mode: "server" | "app";
  directory: string;           // absolute path to the user-data dir
  logger: PluginLogger;        // debug / info / warn / error
  settings: SettingsReader;    // read-only settings access
  storage: PluginStorage;      // read/write per-plugin key-value storage
}

interface SettingsReader {
  get(key: string): string | undefined;     // a global setting
  getOwn(key: string): string | undefined;  // this plugin's namespaced setting
}

The LLM capability moved off PluginContext. It is now on the per-hook HookApi as api.llm, so it can reflect the model configured for each dictation.

Settings are read-only. Pass runtime config through factory options and read it back with getOwn. For state your plugin needs to write, use storage.

PluginLlm

Access to the host’s configured language model, so server-side plugins can run their own LLM calls (classification, tool-calling agents, and so on) reusing the user’s configured cleanup model and stored keys — no separate provider or key configuration required. Reached through api.llm on any server hook.

interface PluginLlm {
  readonly providerId: string; // e.g. "openai", "groq", "freestyle-cloud"
  readonly modelId: string;
  getModel(): unknown;         // an AI SDK LanguageModel — cast at the call site
  generateText(opts: {         // convenience wrapper over the host's generateText
    prompt: string;
    system?: string;
    signal?: AbortSignal;
  }): Promise<{ text: string; usage?: { inputTokens: number; outputTokens: number } }>;
}

api.llm is present only on server hooks and only when a model is configured, so always guard with if (api.llm). Read it fresh in each hook — don’t capture it in setup (it’s built per-dictation):

import { generateText, type LanguageModel } from "ai";

async afterTranscribe(input, output, api) {
  if (!api.llm) return; // no model configured — leave the transcript as-is
  const model = api.llm.getModel() as LanguageModel;
  const { text } = await generateText({ model, prompt: output.text, abortSignal: api.signal });
  output.text = text;
}

For a simple one-shot call you can skip the AI SDK entirely and use the wrapper:

async afterTranscribe(input, output, api) {
  if (!api.llm) return;
  const { text } = await api.llm.generateText({ prompt: output.text, signal: api.signal });
  output.text = text;
}

getModel() is typed unknown in the SDK to avoid a hard dependency on the ai package — cast the result to LanguageModel (from ai) at the call site. Bundle ai in your plugin’s devDependencies; installed plugins don’t get a transitive npm install.

Freestyle Cloud. Signed-in Freestyle Cloud users get api.llm too — it routes to Freestyle Cloud’s managed LLM endpoint, so plugins work without the user configuring their own provider or key. Plugins never see credentials either way: the host resolves the provider, model, and key and hands back only the capability.

PluginStorage

Per-plugin persistent key-value storage, scoped by plugin name so plugins never collide. Values are JSON-serialized into the host database (and sync across machines when the database is synced). Think of it as localStorage for plugins.

interface PluginStorage {
  get<T = unknown>(key: string): Promise<T | undefined>;
  set(key: string, value: unknown): Promise<void>;
  delete(key: string): Promise<void>;
}

Capture it in setup and use it from your hooks or middleware:

setup(ctx) {
  const saved = await ctx.storage.get<MyState>("state");
  // ...
  await ctx.storage.set("state", nextState);
}

Events

const FreestyleEventType = {
  RecordingStarted: "recordingStarted",
  RecordingCommitted: "recordingCommitted",
  RecordingCancelled: "recordingCancelled",
  Transcribed: "transcribed",
  Cleaned: "cleaned",
  OutputDelivered: "outputDelivered",
  PipelineError: "pipelineError",
};

type FreestyleEvent =
  | { type: "recordingStarted" }
  | { type: "recordingCommitted" }
  | { type: "recordingCancelled" }
  | { type: "transcribed"; text: string; durationInSeconds?: number }
  | { type: "cleaned"; before: string; after: string }
  | { type: "outputDelivered"; text: string; mode: OutputMode }
  | { type: "pipelineError"; stage: PipelineStage; message: string };

PipelineStage is "capture" | "transcribe" | "cleanup" | "transform" | "output".

AppContext

Best-effort info about the focused app, on several hook inputs.

interface AppContext {
  appName?: string;
  windowTitle?: string;
  url?: string;
  bundleId?: string;
}

OutputMode

How a transcript is delivered. Set output.mode in beforeOutput.

const OutputMode = {
  Paste: "paste",          // copy, then simulate Cmd/Ctrl+V
  Clipboard: "clipboard",  // copy only
  None: "none",            // suppress
};

transform

Wraps a plain text function into an afterCleanup hook.

function transform(
  fn: (text: string, input: AfterCleanupInput) => string | Promise<string>,
): Handler<AfterCleanupInput, { text: string }>;

The UI bridge

Freestyle injects window.freestyle into plugin pages as the one privileged surface: a helper to call the local server API and to trigger a small set of host actions. See a worked example in the first-plugin guide.

interface FreestyleBridge {
  readonly serverUrl: string;  // origin the page is served from (location.origin)
  api(path: string, init?: RequestInit): Promise<Response>;
  invoke<C extends keyof HostActions>(channel: C, payload: HostActions[C]): Promise<void>;
}

interface HostActions {
  copy: { text: string };
  toast: { message: string; variant?: "info" | "success" | "error" };
  navigate: { to: string };
}

api(path, init?) resolves path against serverUrl and returns a native Response. Plugin UI is now served same-origin with the server, so this is a thin wrapper over fetch (no proxying, no manual token) — call res.json() / res.text() as usual.

const res = await window.freestyle.api("/api/plugins/my-plugin/data");
if (res.ok) console.log(await res.json());

Plugin pages may only reach their own /api/plugins/<slug>/… namespace plus /api/health — the host confines them by the request Referer. They cannot read settings, keys, or history.

invoke(channel, payload) asks the host to do something:

await window.freestyle.invoke("copy", { text: "copied!" });
await window.freestyle.invoke("toast", { message: "Done", variant: "success" });
await window.freestyle.invoke("navigate", { to: "/plugins" });

window.freestyle is only present inside a hosted plugin page, so guard for it (if (!window.freestyle) ...) before use.

Manifest

The freestyle field in package.json.

{
  "freestyle": {
    "icon": "Sparkles",
    "contributes": {
      "pages": [
        { "id": "my-page", "title": "My Page", "entry": "dist/ui/index.html", "icon": "Settings" }
      ]
    }
  }
}

icon is a lucide name.

Getting Started

Features

Plugins

Advanced

Plugin

Hooks

Consuming an utterance

HookApi

PluginContext

PluginLlm

PluginStorage

Events

AppContext

OutputMode

transform

The UI bridge

Manifest

​Plugin

​Hooks

​Consuming an utterance

​HookApi

​PluginContext

​PluginLlm

​PluginStorage

​Events

​AppContext

​OutputMode

​transform

​The UI bridge

​Manifest

Plugin

Hooks

Consuming an utterance

HookApi

PluginContext

PluginLlm

PluginStorage

Events

AppContext

OutputMode

transform

The UI bridge

Manifest