# Overview

dotagent ships with first-party plugins, installed alongside the `dotagent` binary by the Homebrew formula. Each has its own page below with full config schema, behavior details, examples, and troubleshooting.

For the **concept** (what a plugin is, how to use one, how to write one), see [`docs/plugins.md`](/concepts/plugins.md). For the **protocol spec** (verbs, JSON shape, exit codes), see [`docs/reference/plugin-protocol.md`](/reference/plugin-protocol.md).

> **Note on notifications.** Notifications **used to be plugins** (`notify-imessage`, `notify-desktop`, etc). They are now **built into the daemon** under the `[[notifiers]]` array — no plugin subprocess, native APIs (NSUserNotification on macOS, D-Bus on Linux, HTTPS for Slack/ntfy/Pushover). See [`docs/concepts/notifications.md`](/concepts/notifications.md) for the new shape.

## Preflight plugins (`kind = "preflight"`)

Run BEFORE the agent. If any returns `ok=false`, the agent is aborted and `on_failure` fires with `event = "preflight"`.

| Plugin                                                            | Platforms     | When to pick                                                      |
| ----------------------------------------------------------------- | ------------- | ----------------------------------------------------------------- |
| [`preflight-warp`](/built-in-plugins/preflight/preflight-warp.md) | macOS + Linux | Agent depends on a corporate VPN routed via Cloudflare WARP.      |
| [`preflight-cmd`](/built-in-plugins/preflight/preflight-cmd.md)   | macOS + Linux | Generic: run any shell command, gate on exit code + stdout match. |

## Sink plugins (`kind = "sink"`)

Run AFTER a successful agent run. Persist the captured stdout somewhere.

| Plugin                                             | Platforms     | When to pick                                                |
| -------------------------------------------------- | ------------- | ----------------------------------------------------------- |
| [`sink-roam`](/built-in-plugins/sink/sink-roam.md) | macOS + Linux | Output is hierarchical markdown destined for Roam Research. |
| [`sink-file`](/built-in-plugins/sink/sink-file.md) | macOS + Linux | Output is a single file (overwrite or append).              |

## Discovery

dotagent finds these binaries via `$PATH` (Homebrew installs them in `/opt/homebrew/bin/` on Apple silicon / `/usr/local/bin/` on Intel / Linux). Custom plugins go in `~/.config/dotagent/plugins/` or anywhere listed in `$DOTAGENT_PLUGIN_PATH`.

Verify what's available:

```bash
dotagent plugin list
dotagent doctor                                 # validates every reference in your manifests
dotagent-plugin-<name> info | jq .              # raw metadata for any plugin
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dotagent.avelino.run/built-in-plugins/plugins.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.