Vellum Sounds

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/vellum-soundsThe 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: Customize the desktop app's sound effects by adding sound files to the workspace, enabling sounds, setting volume, and assigning sounds to app events

---
name: vellum-sounds
description: Customize the desktop app's sound effects by adding sound files to the workspace, enabling sounds, setting volume, and assigning sounds to app events
compatibility: "Designed for Vellum personal assistants"
metadata:
  emoji: "🔊"
  vellum:
    platforms:
      - macos
      - windows
    category: "content"
    display-name: "Sounds"
---

You are helping the user customize the sound effects their desktop app plays. Sounds are configured in two places: a `data/sounds/` directory of audio files and a `data/sounds/config.json` that controls what plays, at what volume, and whether it is enabled. The Settings > Sounds tab reads the same files on macOS and Windows, so changes appear there live without a restart.

**All commands in this skill use the `bash` tool.** `$VELLUM_WORKSPACE_DIR` is available in the sandbox environment — do not use `host_bash`.

## What you're configuring

Two stores, both under `$VELLUM_WORKSPACE_DIR/data/sounds/`:

- **Sound files:** `.aiff`, `.wav`, `.mp3`, `.m4a`, or `.caf`. No other extensions are accepted. The app scans this directory to populate the dropdown for each event. Prefer `.wav`, `.mp3`, or `.m4a` when the same file must play on both macOS and Windows.
- **`config.json`:** a single JSON file that stores the global on/off switch, the master volume, and a per-event map of `{ enabled, sounds }`. Each event's `sounds` is a **pool** of filenames; the app picks one at random on playback. An empty pool falls back to the platform's default blip.

## Sound events

macOS supports all nine events below. Windows supports the eight events other than `app_open`. Do not configure `app_open` on Windows because it is not displayed or played there. Other keys are ignored by the app.

| Event key          | Fires when                                 |
| ------------------ | ------------------------------------------ |
| `app_open`         | App launches (macOS only)                  |
| `task_complete`    | Conversation transitions processing → idle |
| `needs_input`      | Conversation enters waiting-for-input      |
| `task_failed`      | Conversation enters error state            |
| `notification`     | A tool-triggered notification is sent      |
| `new_conversation` | User creates a new conversation            |
| `message_sent`     | User sends a message in the composer       |
| `character_poke`   | User clicks the avatar                     |
| `random`           | Ambient timer (fires every 5–30 minutes)   |

## Mode 1: Inspect current state

Always check current state before making changes — the user may already have things configured.

```bash
ls "$VELLUM_WORKSPACE_DIR/data/sounds/" 2>/dev/null || echo "No sounds directory yet"
cat "$VELLUM_WORKSPACE_DIR/data/sounds/config.json" 2>/dev/null || echo "No config yet"
```

Report back what's there: whether sounds are globally enabled, current volume, which events have custom sounds assigned.

## Mode 2: Add a sound file

The user either sends you an audio file or asks you to fetch/generate one. Copy it into `data/sounds/` with a clean filename:

```bash
mkdir -p "$VELLUM_WORKSPACE_DIR/data/sounds"
cp "<source-path>" "$VELLUM_WORKSPACE_DIR/data/sounds/<descriptive-name>.<ext>"
```

Rules:

- Extension must be one of: `aiff`, `wav`, `mp3`, `m4a`, `caf`. If the user's file is something else (e.g. `.ogg`, `.flac`), tell them — don't try to rename.
- Keep the filename simple (no path separators, no leading dots). Spaces are fine.
- After adding a file, it's available in the dropdown — but nothing plays until you assign it to an event (Mode 3).

## Mode 3: Configure via the helper script

Use `scripts/update-config.ts` to edit `config.json`. It validates inputs, creates the file with defaults if missing, and writes atomically so a crash can't corrupt it. If the existing file uses the legacy single-sound shape (`"sound": "foo.wav"`), the script normalizes it to the new pool shape (`"sounds": ["foo.wav"]`) on the next write.

```bash
bun run scripts/update-config.ts --global-enabled true
bun run scripts/update-config.ts --volume 0.5
bun run scripts/update-config.ts --event message_sent --enabled true --sound "gentle-ding.aiff"
bun run scripts/update-config.ts --event random --enabled false
bun run scripts/update-config.ts --event task_complete --sound null   # clear the pool, revert to default blip
```

### Mode 3a: Sound pools

Each event can hold **one or more** sounds. When the event fires, the app picks one entry at random from the pool. This is how you build variety, such as three different "poke" sounds that rotate when the user clicks the avatar. An empty pool falls back to the platform's default blip.

```bash
# Replace the pool with three sounds
bun run scripts/update-config.ts --event character_poke --sounds "poke1.wav,poke2.wav,poke3.wav"

# Append one more sound to the existing pool
bun run scripts/update-config.ts --event character_poke --add-sound "poke4.wav"

# Drop a specific entry
bun run scripts/update-config.ts --event character_poke --remove-sound "poke2.wav"

# Empty the pool (back to the default blip)
bun run scripts/update-config.ts --event character_poke --clear-sounds
```

`--sound` is retained as a convenience for the common single-sound case: it **replaces the whole pool** with one entry (or clears it, when given `null`). Use `--sounds` / `--add-sound` / `--remove-sound` / `--clear-sounds` for pool edits.

Only one pool-mutation flag is allowed per invocation — mixing `--sound` and `--add-sound` (or any other pair) is rejected with a clear error. The one exception is `--add-sound`, which may be passed multiple times to append several filenames in a single run.

Flag reference:

| Flag               | Value                     | Effect                                                                                                                                                                     |
| ------------------ | ------------------------- | -----------

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 Vellum Sounds

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

Spotted something wrong? Report a correction · Methodology