Watcher

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/watcherThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Create and manage polling watchers that monitor external services (Gmail, Google Calendar, GitHub, Linear, Outlook) for events and process them with custom action prompts

---
name: watcher
description: Create and manage polling watchers that monitor external services (Gmail, Google Calendar, GitHub, Linear, Outlook) for events and process them with custom action prompts
compatibility: "Designed for Vellum personal assistants"
metadata:
  emoji: "👀"
  vellum:
    category: "productivity"
    display-name: "Watcher"
---

Create and manage watchers that poll external services for events and process them with an action prompt.

## Concepts

- **Provider** - The external service to poll (e.g. "gmail"). Each provider defines how to fetch and parse events.
- **Action prompt** - LLM instructions for handling detected events. Sent along with event data to a background conversation.
- **Poll interval** - How often to check for new events (minimum 15 seconds, default 60 seconds).
- **Digest** - Summary of recent watcher activity, grouped by watcher with time-based filtering.

## Lifecycle

1. Create a watcher with `assistant watchers create`, specifying a name, provider, and action prompt.
2. The system polls the provider at the configured interval.
3. Detected events are processed according to the action prompt.
4. Use `assistant watchers digest` to review recent activity.

## Available Commands

### Create a watcher

```
assistant watchers create \
  --name <name> \
  --provider <provider> \
  --action-prompt <prompt> \
  [--poll-interval <ms>] \
  [--config <json>] \
  [--credential-service <service>]
```

| Flag                   | Required | Description                                                                         |
| ---------------------- | -------- | ----------------------------------------------------------------------------------- |
| `--name`               | Yes      | A human-readable name for this watcher (e.g. "My Gmail")                            |
| `--provider`           | Yes      | The provider to poll (see Available Providers below)                                |
| `--action-prompt`      | Yes      | Instructions for the LLM on how to handle detected events                           |
| `--poll-interval`      | No       | How often to poll in milliseconds. Defaults to 60000 (1 minute). Minimum 15000      |
| `--config`             | No       | Provider-specific configuration as JSON (e.g. filter criteria)                      |
| `--credential-service` | No       | Override the credential service to use. Defaults to the provider's required service |

**Example:**

```bash
assistant watchers create \
  --name "My Gmail" \
  --provider gmail \
  --action-prompt "Summarize new emails and notify me if anything is urgent"
```

### List watchers

```
assistant watchers list [--id <watcherId>] [--enabled-only]
```

| Flag             | Required | Description                                                       |
| ---------------- | -------- | ----------------------------------------------------------------- |
| `--id`           | No       | Show detailed info for a specific watcher including recent events |
| `--enabled-only` | No       | Only show enabled watchers                                        |

**Example:**

```bash
# List all watchers
assistant watchers list

# Show details for a specific watcher
assistant watchers list --id abc123
```

### Update a watcher

```
assistant watchers update <watcherId> \
  [--name <name>] \
  [--action-prompt <prompt>] \
  [--poll-interval <ms>] \
  [--enabled | --disabled] \
  [--config <json>]
```

| Flag              | Required | Description                                           |
| ----------------- | -------- | ----------------------------------------------------- |
| `<watcherId>`     | Yes      | The ID of the watcher to update (positional argument) |
| `--name`          | No       | New name for the watcher                              |
| `--action-prompt` | No       | New action prompt for event processing                |
| `--poll-interval` | No       | New poll interval in milliseconds (minimum 15000)     |
| `--enabled`       | No       | Enable the watcher                                    |
| `--disabled`      | No       | Disable the watcher                                   |
| `--config`        | No       | New provider-specific configuration as JSON           |

**Example:**

```bash
# Change the action prompt
assistant watchers update abc123 --action-prompt "Flag urgent emails and ignore newsletters"

# Disable a watcher temporarily
assistant watchers update abc123 --disabled
```

### Delete a watcher

```
assistant watchers delete <watcherId>
```

Permanently deletes a watcher and all its event history.

**Example:**

```bash
assistant watchers delete abc123
```

### View watcher digest

```
assistant watchers digest [--id <watcherId>] [--hours <n>] [--limit <n>]
```

| Flag      | Required | Description                                                                          |
| --------- | -------- | ------------------------------------------------------------------------------------ |
| `--id`    | No       | Filter to events from a specific watcher. If omitted, shows events from all watchers |
| `--hours` | No       | How many hours back to look. Defaults to 24                                          |
| `--limit` | No       | Maximum number of events to return. Defaults to 50                                   |

**Example:**

```bash
# See all watcher activity from the last 24 hours
assistant watchers digest

# See activity from a specific watcher over the last 8 hours
assistant watchers digest --id abc123 --hours 8
```

## Available Providers

| Provider           | Description                                        |
| ------------------ | -------------------------------------------------- |
| `gmail`            | Monitor a Gmail inbox for new emails               |
| `google-calendar`  | Monitor Google Calendar for new or updated events  |
| `github`           | Monitor GitHub for repository activity             |
| `linear`           | Monitor Linear for issu

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vellum-ai/vellum-assistant
git -C vellum-assistant checkout 19bc86343b63

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Watcher

• github.com/vellum-ai/vellum-assistant/tree/main/skills/watcher — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology