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.

Mode 1: Inspect current state

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

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:

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.

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.

# 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:

The script prints the resulting config slice so you can confirm what changed.

Mode 4: Remove a sound file

rm "$VELLUM_WORKSPACE_DIR/data/sounds/<filename>"

Then remove it from any event pool that referenced it, so the config doesn't dangle:

# If the file was one entry in a larger pool:
bun run scripts/update-config.ts --event <key> --remove-sound "<filename>"

# If the event only had that one sound (or you want to reset entirely):
bun run scripts/update-config.ts --event <key> --clear-sounds

(The app already falls back to the platform's default blip if every referenced file is missing, but cleaning up the config is tidier.)

UX Guidelines

• Always check current state first. Don't ask "what do you want to do" if they already have sounds configured — summarize what's set up, then ask what to change.
• The master switch is the #1 gotcha. globalEnabled defaults to false. If the user assigns a sound to an event and doesn't hear anything, check that flag first. When assigning the user's first sound, offer to flip the master switch on for them.
• Per-event enabled is the #2 gotcha. Each event has its own enabled bool. Setting a sound alone doesn't enable the event.
• Pool editing in the UI. The Settings > Sounds tab supports pool editing on macOS and Windows. Users can add and remove entries there without running this script. Power users can weight a sound more heavily by hand-editing config.json to include duplicates. For example, ["a.wav","a.wav","b.wav"] makes a.wav twice as likely. The script de-dupes on --add-sound but does not re-sort or de-dupe on read, so hand-edited duplicates survive round-trips.
• Filename sanity. When the user sends a file named something like Screen Recording 2026-04-13 at 11.47.23.m4a, rename it to something memorable before copying — they'll have to pick it from a dropdown later.
• Confirm after changes. Tell the user the Settings > Sounds tab will reflect changes live. Offer to open it: "You can preview it in Settings > Sounds, or I can play it for you next time that event fires."
• Don't invent events. macOS supports the nine keys above, while Windows supports eight and excludes app_open. There is currently no event for voice-mode activation or typing indicators. If the user asks for those, tell them it needs a desktop app code change.

Config shape reference

If the user inspects config.json directly, this is the macOS superset they may see. On Windows, omit the app_open entry. Defaults otherwise match the shared desktop sound configuration.

{
  "globalEnabled": false,
  "volume": 0.7,
  "events": {
    "app_open": { "enabled": false, "sounds": [] },
    "task_complete": { "enabled": false, "sounds": [] },
    "needs_input": { "enabled": false, "sounds": [] },
    "task_failed": { "enabled": false, "sounds": [] },
    "notification": { "enabled": false, "sounds": [] },
    "new_conversation": { "enabled": false, "sounds": [] },
    "message_sent": { "enabled": false, "sounds": [] },
    "character_poke": { "enabled": false, "sounds": [] },
    "random": { "enabled": false, "sounds": [] }
  }
}

Legacy {"sound": "foo.wav"} entries are still accepted on read (the macOS decoder and this script both normalize them into {"sounds": ["foo.wav"]}), but new writes always use the pool shape.

Details