> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freestylevoice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How plugins work

> The pipeline, the hooks, and where your code runs.

Plugins are custom services that you build that live inside of Freestyle's dictation pipeline. Some of the things that you can do with plugins, just to throw some ideas out there.

* Rewrite transcriptions on each step. Do some custom modifications that Freestyle as is cannot do.
* Tweak the post-processing feed-up step whatever way that you like.
* Reroute the output. Send transcriptions to any external service of your own.

## An overview of Freestyle's Stack

* The **server** owns transcription, cleanup, settings, and the plugin database. Most hooks run here.
* The **app** (the Electron client) owns audio capture, the UI, and delivering text to your window. A couple of hooks run here.

You write one plugin object. Freestyle calls each hook in the right process.

## The pipeline

```
User presses hotkey
        |
        v
[APP]    Capture audio  ......... event: recordingStarted
        |
        v
[SERVER] Speech-to-text
        |                  |-- beforeTranscribe  (preprocess audio, pick model, or consume)
        |                  v
        |                 raw transcript
        |                  |-- afterTranscribe   (rewrite, or consume as an action)
        |                  +-- event: transcribed
        v
[SERVER] AI cleanup (optional)
        |                  |-- beforeCleanup     (shape the prompt + destination tone)
        |                  |-- dictionary + LLM rewrite
        |                  |-- afterCleanup      (rewrite the final text)
        |                  +-- event: cleaned
        v
[APP]    Deliver output
        |                  |-- beforeOutput      (rewrite, suppress, or reroute)
        |                  +-- event: outputDelivered
        v
Text appears in your focused app
```

Every mutating hook also receives an `api` argument: `api.control` cancels or consumes the run (`consume()` skips the rest of the pipeline and delivers nothing — how a voice command "eats" an utterance), and `api.llm` exposes the host's configured LLM to server hooks. See the [SDK reference](/sdk-reference#hookapi).

Building a plugin allows you to modify what happens at each step of Freestyle's dictation pipeline. The SDK offers hooks like `afterTranscribe` and `beforeOutput` that lets you control the inputs and the outputs at each step of the pipeline. In those hooks you can write functions that can do anything as long as it runs properly in a node environment.

## Where plugins live

Installed plugins sit in the user-data directory under `plugins/<slug>/`. Two settings control loading:

* `plugins`: a JSON array of specifiers, or `[specifier, options]` tuples.
* `disabled_plugins`: specifiers to skip.

```json theme={null}
[
  "@freestyle-voice/plugin-audio-transcription",
  ["@freestyle-voice/profanity-filter", { "preserveCase": true }]
]
```

Most people manage these in **Settings → Plugins**.

## Sandboxing

* Each plugin's settings live under `plugin:<name>:<key>`, isolated from other plugins.
* A throwing hook is caught and reported. It won't break the pipeline.
* UI pages are served by the local server at `/api/plugins/<slug>/ui/*` and confined by the host to their own `/api/plugins/<slug>/…` namespace (plus `/api/health`) — no filesystem access, and no reach into settings, keys, or history. They call the server through `window.freestyle`.

## Plugin pages in the app

A plugin that ships a UI page (via `contributes.pages` in its manifest) appears automatically as an item in the app's sidebar, under the built-in sections. Enabling or disabling the plugin adds or removes its nav entry.

Next: [build your first plugin](/first-plugin).