pi startup sound skill — set a custom YouTube clip as your pi coding agent startup sound

download-clip.sh

#!/usr/bin/env bash
set -euo pipefail

URL="${1:?Usage: download-clip.sh <youtube-url> <start> <end> [pi|claude|both]}"
START="${2:?Usage: download-clip.sh <youtube-url> <start> <end> [pi|claude|both]}"
END="${3:?Usage: download-clip.sh <youtube-url> <start> <end> [pi|claude|both]}"
TARGET="${4:-both}"

# Check dependencies
for cmd in yt-dlp ffmpeg; do
  if ! command -v "$cmd" &>/dev/null; then
    echo "Error: $cmd is not installed. Run: brew install $cmd"
    exit 1
  fi
done

TMPDIR="$(mktemp -d)"
trap 'rm -rf "$TMPDIR"' EXIT

echo "Downloading clip from $START to $END..."
yt-dlp \
  --download-sections "*${START}-${END}" \
  -x --audio-format mp3 \
  --force-overwrites \
  -o "${TMPDIR}/startup.%(ext)s" \
  "$URL"

install_to() {
  mkdir -p "$1"
  cp "${TMPDIR}/startup.mp3" "$1/startup.mp3"
  echo "✓ Saved to $1/startup.mp3"
}

case "$TARGET" in
  pi)     install_to "$HOME/.pi/agent/sounds" ;;
  claude) install_to "$HOME/.claude/sounds" ;;
  both)
    install_to "$HOME/.pi/agent/sounds"
    install_to "$HOME/.claude/sounds"
    ;;
  *) echo "Error: target must be 'pi', 'claude', or 'both'"; exit 1 ;;
esac

echo ""
echo "  Run: afplay <path>/startup.mp3   # to preview"

install-extension.sh

#!/usr/bin/env bash
# Install startup sound extension for Pi
set -euo pipefail

EXT_DIR="$HOME/.pi/agent/extensions"
mkdir -p "$EXT_DIR"

cat > "$EXT_DIR/startup-sound.ts" << 'EOF'
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { homedir } from "node:os";
import { join } from "node:path";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async () => {
    const sound = join(homedir(), ".pi", "agent", "sounds", "startup.mp3");
    pi.exec("afplay", [sound], { timeout: 10000 }).catch(() => {});
  });
}
EOF

echo "✓ Installed startup-sound extension to ${EXT_DIR}/startup-sound.ts"
echo "  Restart pi to hear your startup sound."

install-hook.sh

#!/usr/bin/env bash
# Install startup sound SessionStart hook for Claude Code
set -euo pipefail

SETTINGS="$HOME/.claude/settings.json"
SOUND="$HOME/.claude/sounds/startup.mp3"

if [ ! -f "$SOUND" ]; then
  echo "Error: No startup sound found at $SOUND"
  echo "Run download-clip.sh first:  bash download-clip.sh <url> <start> <end> claude"
  exit 1
fi

if ! command -v jq &>/dev/null; then
  echo "Error: jq is not installed. Run: brew install jq"
  exit 1
fi

# Create settings file if it doesn't exist
if [ ! -f "$SETTINGS" ]; then
  echo '{}' > "$SETTINGS"
fi

HOOK='{"type":"command","command":"afplay '"$SOUND"'","timeout":15,"async":true}'

if jq -e '.hooks.SessionStart[0].hooks' "$SETTINGS" &>/dev/null; then
  # Append to existing SessionStart hooks array
  jq --argjson hook "$HOOK" \
    '.hooks.SessionStart[0].hooks += [$hook]' \
    "$SETTINGS" > "${SETTINGS}.tmp" && mv "${SETTINGS}.tmp" "$SETTINGS"
else
  # Create the SessionStart hook
  jq --argjson hook "$HOOK" \
    '.hooks //= {} | .hooks.SessionStart = [{"hooks": [$hook]}]' \
    "$SETTINGS" > "${SETTINGS}.tmp" && mv "${SETTINGS}.tmp" "$SETTINGS"
fi

echo "✓ Added startup sound hook to $SETTINGS"
echo "  Restart Claude Code to hear your startup sound."

SKILL.md

name	description
startup-sound	Set a custom startup sound for pi and/or Claude Code from a YouTube video clip. Installs dependencies (yt-dlp, ffmpeg), downloads a time range, and wires up a session-start hook to play it. Use when someone wants their agent to play a sound on launch.

Startup Sound

Set a custom startup sound for Pi and/or Claude Code using a clip from any YouTube video.

Prerequisites

Install yt-dlp and ffmpeg via Homebrew (macOS):

brew install yt-dlp ffmpeg

Claude Code hook installation also requires jq:

brew install jq

Setup

1. Download a clip

Use the helper script to download a time range from a YouTube video as an mp3:

bash download-clip.sh "<youtube-url>" "<start>" "<end>" [pi|claude|both]

• <start> and <end> are timestamps like 0:03 or 1:30
• The fourth argument selects the target agent (defaults to both)

Target	Sound path
pi	~/.pi/agent/sounds/startup.mp3
claude	~/.claude/sounds/startup.mp3
both	Both of the above

Example:

bash download-clip.sh "https://www.youtube.com/watch?v=dQw4w9WgXcQ" "0:00" "0:05"

2. Install the hook

For Pi:

bash install-extension.sh

This creates a Pi extension at ~/.pi/agent/extensions/startup-sound.ts that plays the sound on session_start.

For Claude Code:

bash install-hook.sh

This adds a SessionStart hook to ~/.claude/settings.json that plays the sound via afplay.

3. Restart your agent

The sound will play on every session start. To change the sound, run step 1 again with a different video/range.

How it works

Agent	Mechanism	Config location
Pi	Extension (session_start event)	~/.pi/agent/extensions/startup-sound.ts
Claude Code	SessionStart hook (afplay, async)	~/.claude/settings.json

Uninstall

Pi:

rm ~/.pi/agent/extensions/startup-sound.ts
rm -rf ~/.pi/agent/sounds/

Claude Code:

Remove the afplay hook entry from ~/.claude/settings.json under hooks.SessionStart, then:

rm -rf ~/.claude/sounds/