# Codevator

> 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.

- Skill: `educlopez/codevator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add educlopez/codevator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/educlopez/codevator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: educlopez (https://skillmd.com/u/educlopez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/educlopez/codevator

---


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