You control codevator, a CLI that plays background music while AI coding agents work. It hooks into agents so music starts/stops automatically with sessions.
Quick Reference
All commands: npx codevator <command> (or codevator if globally installed).
Playback
| Command |
What it does |
mode <name> |
Switch to a sound (e.g. mode lofi-relax) |
mode --random |
Pick a random installed sound |
mode --random --category <cat> |
Random within a category |
on / off |
Enable or disable sounds |
play / stop |
Start or stop playback |
volume <0-100> |
Set volume |
preview <name> |
Preview a sound for 5 seconds |
Sound Management
| Command |
What it does |
list |
List all sounds grouped by category |
list --category <cat> |
List sounds in a category |
add [name] |
Download sounds from the registry |
add --category <cat> |
Browse and download by category |
import <file> --name <n> |
Import a custom audio file (mp3/wav/ogg/m4a) |
remove <name> |
Remove a custom sound |
Setup & Diagnostics
| Command |
What it does |
setup |
Install hooks for Claude Code (default) |
setup --agent <name> |
Install hooks for a specific agent |
status |
Show current mode, volume, agent, mini-stats |
stats |
Full stats: plays, time, streaks, milestones |
doctor |
Diagnose issues (hooks, audio, config, sounds) |
uninstall |
Remove all hooks |
Profiles
| Command |
What it does |
profile create <name> |
Save current mode + volume as a preset |
profile use <name> |
Switch to a saved profile |
profile list |
List all profiles |
profile delete <name> |
Delete a profile |
macOS Menu Bar
| Command |
What it does |
install-menubar |
Install the macOS menu bar controller |
uninstall-menubar |
Remove menu bar app |
Available Sounds
Focus & Ambient: elevator (default), typewriter, minimal, lofi-relax, lofi-chill, lofi-cozy
Nature: ambient, rain, forest, ocean
Music & Retro: retro, classical-piano, ambient-guitar, epic-strings
Integration: spotify (controls Spotify volume on macOS — not a sound file)
Categories for --category flag: focus, nature, music, integration
Supported Agents
claude (default), codex, gemini, copilot, cursor, windsurf, opencode
Example: npx codevator setup --agent gemini
Behavior
- When the user asks to change sounds/music/modes, run the command and confirm briefly
- When asked "what sounds are available", run
list or describe from the table above
- For troubleshooting, suggest
doctor first
- Spotify mode requires macOS and an active Spotify session
1---2name: codevator3description: Control codevator — background music and sounds for AI coding agents. Use when the user mentions music, sounds, elevator music, background audio, coding music, volume, mute, sound modes, lo-fi, nature sounds, ambient, retro, focus music, or /codevator. Also use when the user wants to set up codevator with a new agent, check playback stats, manage sound profiles, import custom sounds, or preview available sounds.4---56You control **codevator**, a CLI that plays background music while AI coding agents work. It hooks into agents so music starts/stops automatically with sessions.78## Quick Reference910All commands: `npx codevator <command>` (or `codevator` if globally installed).1112### Playback1314| Command | What it does |15|---------|-------------|16| `mode <name>` | Switch to a sound (e.g. `mode lofi-relax`) |17| `mode --random` | Pick a random installed sound |18| `mode --random --category <cat>` | Random within a category |19| `on` / `off` | Enable or disable sounds |20| `play` / `stop` | Start or stop playback |21| `volume <0-100>` | Set volume |22| `preview <name>` | Preview a sound for 5 seconds |2324### Sound Management2526| Command | What it does |27|---------|-------------|28| `list` | List all sounds grouped by category |29| `list --category <cat>` | List sounds in a category |30| `add [name]` | Download sounds from the registry |31| `add --category <cat>` | Browse and download by category |32| `import <file> --name <n>` | Import a custom audio file (mp3/wav/ogg/m4a) |33| `remove <name>` | Remove a custom sound |3435### Setup & Diagnostics3637| Command | What it does |38|---------|-------------|39| `setup` | Install hooks for Claude Code (default) |40| `setup --agent <name>` | Install hooks for a specific agent |41| `status` | Show current mode, volume, agent, mini-stats |42| `stats` | Full stats: plays, time, streaks, milestones |43| `doctor` | Diagnose issues (hooks, audio, config, sounds) |44| `uninstall` | Remove all hooks |4546### Profiles4748| Command | What it does |49|---------|-------------|50| `profile create <name>` | Save current mode + volume as a preset |51| `profile use <name>` | Switch to a saved profile |52| `profile list` | List all profiles |53| `profile delete <name>` | Delete a profile |5455### macOS Menu Bar5657| Command | What it does |58|---------|-------------|59| `install-menubar` | Install the macOS menu bar controller |60| `uninstall-menubar` | Remove menu bar app |6162## Available Sounds6364**Focus & Ambient**: elevator (default), typewriter, minimal, lofi-relax, lofi-chill, lofi-cozy6566**Nature**: ambient, rain, forest, ocean6768**Music & Retro**: retro, classical-piano, ambient-guitar, epic-strings6970**Integration**: spotify (controls Spotify volume on macOS — not a sound file)7172Categories for `--category` flag: `focus`, `nature`, `music`, `integration`7374## Supported Agents7576claude (default), codex, gemini, copilot, cursor, windsurf, opencode7778Example: `npx codevator setup --agent gemini`7980## Behavior8182- When the user asks to change sounds/music/modes, run the command and confirm briefly83- When asked "what sounds are available", run `list` or describe from the table above84- For troubleshooting, suggest `doctor` first85- Spotify mode requires macOS and an active Spotify session
educlopez