Documentation
Set up in 30 seconds
One command. Background music plays while your agent works, stops when it's done. No config needed.
Quick start
Install codevator via npx. It sets up hooks and downloads the default sound:
npx codevator
Done. Next time your agent starts working, elevator music plays. When it finishes or waits for input, the music stops. Fully automatic.
Multi-agent support
Codevator works with 7 coding agents. Pick yours during setup:
npx codevator setup --agent claude
claudeClaude Code (default)codexCodex CLIgeminiGemini CLIcopilotCopilot CLIcursorCursorwindsurfWindsurfopencodeOpenCodeAll agents share the same sounds, config, and profiles. You can set up multiple agents on the same machine.
Agent skill
Want your agent to change music for you? Install the codevator skill:
npx skills add educlopez/codevator
Skills is an open registry for agent capabilities — learn more on GitHub.
Works across Claude Code, Cursor, Windsurf, Gemini CLI, and 30+ other agents. Once installed, just ask:
- “Play some lo-fi while I review this PR”
- “Switch to nature sounds”
- “Turn the volume down to 30”
- “Show me my listening stats”
Your agent runs the right codevator command behind the scenes.
Sounds
15 sounds across three categories. Pick what fits your flow.
Focus & Ambient
elevatorSmooth jazz elevator music (default)typewriterRhythmic mechanical keystrokesminimalDeep warm hum with slow breathinglofi-relaxLaid-back lo-fi beatslofi-chillMellow lo-fi grooveslofi-cozyWarm lo-fi vibesNature
ambientGentle atmospheric backgroundrainSteady rainfallforestBirds and rustling leavesoceanGentle ocean wavesMusic & Retro
retroMellow 8-bit synthesized arpeggiosclassical-pianoSoft classical piano piecesambient-guitarGentle fingerpicked guitarepic-stringsCinematic orchestral stringsspotifyFades your Spotify in/out with coding sessions (macOS)Switch modes any time:
npx codevator mode lofi-relax
Run npx codevator mode without a name to browse an interactive picker. Add --random for a surprise, or --category focus to filter.
Preview and browse all sounds at codevator.dev/sounds.
Custom sounds
Download more sounds from the registry:
npx codevator add
Or grab a specific one:
npx codevator add rain
Bring your own audio too. Import any mp3, wav, ogg, or m4a file:
npx codevator import my-music.mp3 --name chill
Your custom sounds show up alongside built-in ones. Remove them with npx codevator remove chill.
Profiles
Save mode + volume combos as presets. A quiet ambient setup for deep work, louder retro for background tasks — switch instantly.
npx codevator profile create deepwork npx codevator profile use deepwork
List all profiles with profile list, remove with profile delete. Profiles live in ~/.codevator/config.json.
Commands
npx codevatorInstall hooks and download default soundnpx codevator mode [name]Set sound mode (--random, --category)npx codevator add [name]Download a sound from the registrynpx codevator on / offEnable or disable soundsnpx codevator volume <n>Set volume (0–100)npx codevator listShow all sounds grouped by categorynpx codevator preview <mode>Play a 5-second previewnpx codevator statsPlay time, streaks, and milestonesnpx codevator statusCurrent settings and quick statsnpx codevator import <file>Import a custom audio filenpx codevator remove <name>Delete a custom soundnpx codevator profile <action>Manage presets (create, use, list, delete)npx codevator doctorDiagnose installation issuesnpx codevator install-menubarInstall the macOS menubar appnpx codevator uninstallRemove hooks from your agentUnder the hood
Codevator registers hooks in your agent's config. For Claude Code, that's ~/.claude/settings.json:
PreToolUseStarts playback when the agent begins workingStopStops playback when the session endsNotificationPauses on permission prompts and idle statesAudio plays through your system's native player — afplay on macOS, paplay or aplay on Linux. Sounds are downloaded on demand from codevator.dev and cached in ~/.codevator/sounds/.
Configuration
All settings live in ~/.codevator/config.json:
{
"mode": "elevator",
"volume": 70,
"enabled": true
}modeActive sound modevolumePlayback volume (0–100)enabledWhether sounds play on hook triggersUninstall
Remove hooks from your agent:
npx codevator uninstall
This removes the hooks only. Your config and downloaded sounds at ~/.codevator/ are kept. Delete that folder manually for a full cleanup.
Found a bug? Open an issue on GitHub.
Background music that plays while your AI agent codes — and stops when it's done.
© 2026 Codevator · MIT licensed · built by @educalvolpz

