Add peon --pack CLI command with autocomplete and cycling

- `peon --packs` lists available packs, marks active with *
- `peon --pack <name>` switches to a specific pack with validation
- `peon --pack` (no arg) cycles to the next pack alphabetically
- Tab completion for `peon --pack <TAB>` via completions.bash
- install.sh sources completions in .zshrc/.bashrc
- Updated --help output and README documentation
- 14 new bats tests covering all pack switching scenarios

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: garysheng

README.md

@@ -41,11 +41,16 @@ Need to mute sounds and notifications during a meeting or pairing session? Two o
 Other CLI commands:
 
 ```bash
-peon --pause    # Mute sounds
-peon --resume   # Unmute sounds
-peon --status   # Check if paused or active
+peon --pause          # Mute sounds
+peon --resume         # Unmute sounds
+peon --status         # Check if paused or active
+peon --packs          # List available sound packs
+peon --pack <name>    # Switch to a specific pack
+peon --pack           # Cycle to the next pack
 ```
 
+Tab completion is supported — type `peon --pack <TAB>` to see available pack names.
+
 Pausing mutes sounds and desktop notifications instantly. Persists across sessions until you resume. Tab titles remain active when paused.
 
 ## Configuration
@@ -83,7 +88,15 @@ Edit `~/.claude/hooks/peon-ping/config.json`:
 | `sc_battlecruiser` | Battlecruiser (StarCraft) | "Battlecruiser operational", "Make it happen", "Engage" | [@garysheng](https://github.com/garysheng) |
 | `sc_kerrigan` | Sarah Kerrigan (StarCraft) | "I gotcha", "What now?", "Easily amused, huh?" | [@garysheng](https://github.com/garysheng) |
 
-Switch packs in `~/.claude/hooks/peon-ping/config.json`:
+Switch packs from the CLI:
+
+```bash
+peon --pack ra2_soviet_engineer   # switch to a specific pack
+peon --pack                       # cycle to the next pack
+peon --packs                      # list all packs
+```
+
+Or edit `~/.claude/hooks/peon-ping/config.json` directly:
 
 ```json
 { "active_pack": "ra2_soviet_engineer" }

completions.bash

@@ -0,0 +1,34 @@
+#!/bin/bash
+# peon-ping tab completion for bash and zsh
+
+_peon_completions() {
+  local cur prev opts packs_dir
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Top-level options
+  opts="--pause --resume --toggle --status --packs --pack --help"
+
+  if [ "$prev" = "--pack" ]; then
+    # Complete pack names by scanning manifest files
+    packs_dir="${CLAUDE_PEON_DIR:-$HOME/.claude/hooks/peon-ping}/packs"
+    if [ -d "$packs_dir" ]; then
+      local names
+      names=$(find "$packs_dir" -maxdepth 2 -name manifest.json -exec dirname {} \; 2>/dev/null | xargs -I{} basename {} | sort)
+      COMPREPLY=( $(compgen -W "$names" -- "$cur") )
+    fi
+    return 0
+  fi
+
+  COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+  return 0
+}
+
+complete -F _peon_completions peon
+
+# zsh compatibility: if running under zsh, enable bashcompinit
+if [ -n "$ZSH_VERSION" ]; then
+  autoload -Uz bashcompinit 2>/dev/null && bashcompinit
+  complete -F _peon_completions peon
+fi

config.json

@@ -13,4 +13,4 @@
   },
   "annoyed_threshold": 3,
   "annoyed_window_seconds": 10
-}
+}

install.sh

@@ -65,6 +65,7 @@ if [ -n "$SCRIPT_DIR" ]; then
   # Local clone — copy files directly (including sounds)
   cp -r "$SCRIPT_DIR/packs/"* "$INSTALL_DIR/packs/"
   cp "$SCRIPT_DIR/peon.sh" "$INSTALL_DIR/"
+  cp "$SCRIPT_DIR/completions.bash" "$INSTALL_DIR/"
   cp "$SCRIPT_DIR/VERSION" "$INSTALL_DIR/"
   if [ "$UPDATING" = false ]; then
     cp "$SCRIPT_DIR/config.json" "$INSTALL_DIR/"
@@ -73,6 +74,7 @@ else
   # curl|bash — download from GitHub (sounds are version-controlled in repo)
   echo "Downloading from GitHub..."
   curl -fsSL "$REPO_BASE/peon.sh" -o "$INSTALL_DIR/peon.sh"
+  curl -fsSL "$REPO_BASE/completions.bash" -o "$INSTALL_DIR/completions.bash"
   curl -fsSL "$REPO_BASE/VERSION" -o "$INSTALL_DIR/VERSION"
   curl -fsSL "$REPO_BASE/uninstall.sh" -o "$INSTALL_DIR/uninstall.sh"
   for pack in $PACKS; do
@@ -125,6 +127,15 @@ for rcfile in "$HOME/.zshrc" "$HOME/.bashrc"; do
   fi
 done
 
+# --- Add tab completion ---
+COMPLETION_LINE='[ -f ~/.claude/hooks/peon-ping/completions.bash ] && source ~/.claude/hooks/peon-ping/completions.bash'
+for rcfile in "$HOME/.zshrc" "$HOME/.bashrc"; do
+  if [ -f "$rcfile" ] && ! grep -qF 'peon-ping/completions.bash' "$rcfile"; then
+    echo "$COMPLETION_LINE" >> "$rcfile"
+    echo "Added tab completion to $(basename "$rcfile")"
+  fi
+done
+
 # --- Verify sounds are installed ---
 echo ""
 for pack in $PACKS; do

peon.sh

@@ -19,11 +19,100 @@ case "${1:-}" in
   --status)
     [ -f "$PAUSED_FILE" ] && echo "peon-ping: paused" || echo "peon-ping: active"
     exit 0 ;;
+  --packs)
+    /usr/bin/python3 -c "
+import json, os, glob
+config_path = '$CONFIG'
+try:
+    active = json.load(open(config_path)).get('active_pack', 'peon')
+except:
+    active = 'peon'
+packs_dir = '$PEON_DIR/packs'
+for m in sorted(glob.glob(os.path.join(packs_dir, '*/manifest.json'))):
+    info = json.load(open(m))
+    name = info.get('name', os.path.basename(os.path.dirname(m)))
+    display = info.get('display_name', name)
+    marker = ' *' if name == active else ''
+    print(f'  {name:24s} {display}{marker}')
+"
+    exit 0 ;;
+  --pack)
+    PACK_ARG="${2:-}"
+    if [ -z "$PACK_ARG" ]; then
+      # No argument — cycle to next pack alphabetically
+      /usr/bin/python3 -c "
+import json, os, glob
+config_path = '$CONFIG'
+try:
+    cfg = json.load(open(config_path))
+except:
+    cfg = {}
+active = cfg.get('active_pack', 'peon')
+packs_dir = '$PEON_DIR/packs'
+names = sorted([
+    os.path.basename(os.path.dirname(m))
+    for m in glob.glob(os.path.join(packs_dir, '*/manifest.json'))
+])
+if not names:
+    print('Error: no packs found', flush=True)
+    raise SystemExit(1)
+try:
+    idx = names.index(active)
+    next_pack = names[(idx + 1) % len(names)]
+except ValueError:
+    next_pack = names[0]
+cfg['active_pack'] = next_pack
+json.dump(cfg, open(config_path, 'w'), indent=2)
+# Read display name
+mpath = os.path.join(packs_dir, next_pack, 'manifest.json')
+display = json.load(open(mpath)).get('display_name', next_pack)
+print(f'peon-ping: switched to {next_pack} ({display})')
+"
+    else
+      # Argument given — set specific pack
+      /usr/bin/python3 -c "
+import json, os, glob, sys
+config_path = '$CONFIG'
+pack_arg = '$PACK_ARG'
+packs_dir = '$PEON_DIR/packs'
+names = sorted([
+    os.path.basename(os.path.dirname(m))
+    for m in glob.glob(os.path.join(packs_dir, '*/manifest.json'))
+])
+if pack_arg not in names:
+    print(f'Error: pack \"{pack_arg}\" not found.', file=sys.stderr)
+    print(f'Available packs: {\", \".join(names)}', file=sys.stderr)
+    sys.exit(1)
+try:
+    cfg = json.load(open(config_path))
+except:
+    cfg = {}
+cfg['active_pack'] = pack_arg
+json.dump(cfg, open(config_path, 'w'), indent=2)
+mpath = os.path.join(packs_dir, pack_arg, 'manifest.json')
+display = json.load(open(mpath)).get('display_name', pack_arg)
+print(f'peon-ping: switched to {pack_arg} ({display})')
+" || exit 1
+    fi
+    exit 0 ;;
   --help|-h)
-    echo "Usage: peon --pause | --resume | --toggle | --status"; exit 0 ;;
+    cat <<'HELPEOF'
+Usage: peon <command>
+
+Commands:
+  --pause        Mute sounds
+  --resume       Unmute sounds
+  --toggle       Toggle mute on/off
+  --status       Check if paused or active
+  --packs        List available sound packs
+  --pack <name>  Switch to a specific pack
+  --pack         Cycle to the next pack
+  --help         Show this help
+HELPEOF
+    exit 0 ;;
   --*)
     echo "Unknown option: $1" >&2
-    echo "Usage: peon --pause | --resume | --toggle | --status" >&2; exit 1 ;;
+    echo "Run 'peon --help' for usage." >&2; exit 1 ;;
 esac
 
 INPUT=$(cat)

tests/install.bats

@@ -15,6 +15,7 @@ setup() {
   cp "$(dirname "$BATS_TEST_FILENAME")/../peon.sh" "$CLONE_DIR/"
   cp "$(dirname "$BATS_TEST_FILENAME")/../config.json" "$CLONE_DIR/"
   cp "$(dirname "$BATS_TEST_FILENAME")/../VERSION" "$CLONE_DIR/"
+  cp "$(dirname "$BATS_TEST_FILENAME")/../completions.bash" "$CLONE_DIR/"
   cp "$(dirname "$BATS_TEST_FILENAME")/../uninstall.sh" "$CLONE_DIR/" 2>/dev/null || touch "$CLONE_DIR/uninstall.sh"
   cp -r "$(dirname "$BATS_TEST_FILENAME")/../packs" "$CLONE_DIR/"
 
@@ -86,3 +87,14 @@ print('OK')
   bash "$CLONE_DIR/install.sh"
   [ -x "$INSTALL_DIR/peon.sh" ]
 }
+
+@test "fresh install copies completions.bash" {
+  bash "$CLONE_DIR/install.sh"
+  [ -f "$INSTALL_DIR/completions.bash" ]
+}
+
+@test "fresh install adds completions source to shell rc" {
+  touch "$TEST_HOME/.zshrc"
+  bash "$CLONE_DIR/install.sh"
+  grep -qF 'peon-ping/completions.bash' "$TEST_HOME/.zshrc"
+}

tests/peon.bats

@@ -324,3 +324,106 @@ JSON
   [ "$PEON_EXIT" -eq 0 ]
   ! afplay_was_called
 }
+
+# ============================================================
+# --packs (list packs)
+# ============================================================
+
+@test "--packs lists all available packs" {
+  run bash "$PEON_SH" --packs
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"peon"* ]]
+  [[ "$output" == *"sc_kerrigan"* ]]
+}
+
+@test "--packs marks the active pack with *" {
+  run bash "$PEON_SH" --packs
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Orc Peon *"* ]]
+  # sc_kerrigan should NOT be marked
+  line=$(echo "$output" | grep "sc_kerrigan")
+  [[ "$line" != *"*"* ]]
+}
+
+@test "--packs marks correct pack after switch" {
+  bash "$PEON_SH" --pack sc_kerrigan
+  run bash "$PEON_SH" --packs
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Sarah Kerrigan (StarCraft) *"* ]]
+}
+
+# ============================================================
+# --pack <name> (set specific pack)
+# ============================================================
+
+@test "--pack <name> switches to valid pack" {
+  run bash "$PEON_SH" --pack sc_kerrigan
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"switched to sc_kerrigan"* ]]
+  [[ "$output" == *"Sarah Kerrigan"* ]]
+  # Verify config was updated
+  active=$(/usr/bin/python3 -c "import json; print(json.load(open('$TEST_DIR/config.json'))['active_pack'])")
+  [ "$active" = "sc_kerrigan" ]
+}
+
+@test "--pack <name> preserves other config fields" {
+  bash "$PEON_SH" --pack sc_kerrigan
+  volume=$(/usr/bin/python3 -c "import json; print(json.load(open('$TEST_DIR/config.json'))['volume'])")
+  [ "$volume" = "0.5" ]
+}
+
+@test "--pack <name> errors on nonexistent pack" {
+  run bash "$PEON_SH" --pack nonexistent
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"not found"* ]]
+  [[ "$output" == *"Available packs"* ]]
+}
+
+@test "--pack <name> does not modify config on invalid pack" {
+  bash "$PEON_SH" --pack nonexistent || true
+  active=$(/usr/bin/python3 -c "import json; print(json.load(open('$TEST_DIR/config.json'))['active_pack'])")
+  [ "$active" = "peon" ]
+}
+
+# ============================================================
+# --pack (cycle, no argument)
+# ============================================================
+
+@test "--pack cycles to next pack alphabetically" {
+  # Active is peon, next alphabetically is sc_kerrigan
+  run bash "$PEON_SH" --pack
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"switched to sc_kerrigan"* ]]
+}
+
+@test "--pack cycle wraps around from last to first" {
+  # Set to sc_kerrigan (last alphabetically), should wrap to peon
+  bash "$PEON_SH" --pack sc_kerrigan
+  run bash "$PEON_SH" --pack
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"switched to peon"* ]]
+}
+
+@test "--pack cycle updates config correctly" {
+  bash "$PEON_SH" --pack
+  active=$(/usr/bin/python3 -c "import json; print(json.load(open('$TEST_DIR/config.json'))['active_pack'])")
+  [ "$active" = "sc_kerrigan" ]
+}
+
+# ============================================================
+# --help (updated)
+# ============================================================
+
+@test "--help shows pack commands" {
+  run bash "$PEON_SH" --help
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"--packs"* ]]
+  [[ "$output" == *"--pack"* ]]
+}
+
+@test "unknown option shows helpful error" {
+  run bash "$PEON_SH" --foobar
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"Unknown option"* ]]
+  [[ "$output" == *"peon --help"* ]]
+}

tests/setup.bash

@@ -7,6 +7,7 @@ setup_test_env() {
 
   # Create directory structure
   mkdir -p "$TEST_DIR/packs/peon/sounds"
+  mkdir -p "$TEST_DIR/packs/sc_kerrigan/sounds"
 
   # Create minimal manifest
   cat > "$TEST_DIR/packs/peon/manifest.json" <<'JSON'
@@ -56,6 +57,30 @@ JSON
     touch "$TEST_DIR/packs/peon/sounds/$f"
   done
 
+  # Create second pack manifest (for pack switching tests)
+  cat > "$TEST_DIR/packs/sc_kerrigan/manifest.json" <<'JSON'
+{
+  "name": "sc_kerrigan",
+  "display_name": "Sarah Kerrigan (StarCraft)",
+  "categories": {
+    "greeting": {
+      "sounds": [
+        { "file": "Hello1.wav", "line": "What now?" }
+      ]
+    },
+    "complete": {
+      "sounds": [
+        { "file": "Done1.wav", "line": "I gotcha." }
+      ]
+    }
+  }
+}
+JSON
+
+  for f in Hello1.wav Done1.wav; do
+    touch "$TEST_DIR/packs/sc_kerrigan/sounds/$f"
+  done
+
   # Create default config
   cat > "$TEST_DIR/config.json" <<'JSON'
 {