Never wonder when your
long-running build finished.
vv is the polite command-line wrapper. Run tasks quietly in the background with nice & ionice, time execution, flush dirty kernel caches, and get alerted with audio chimes and desktop notifications the moment it completes.
Installs to /usr/local/bin/vv. Zero external dependencies.
ca-pub-8973108060277483Why developers use vv
Everything you need for running background builds politely without bogging down your desktop.
Polite CPU & I/O Scheduling
Wraps commands in nice -n19 and ionice -c3. Compile massive codebases or transcode video without UI freezing, audio stuttering, or input lag.
Kernel Cache Synchronization
Runs time sync upon completion. Many disk writes are held in RAM page cache; vv lets you know the true completion time including disk commit.
Exit Code Fidelity
Faithfully preserves and returns the command's exact exit code ($?). If make or cargo test fails, vv propagates the failure status.
Success vs. Failure Audio Cues
Plays distinct chimes: a pleasing chime for success, or an alert chord for failed builds. Know the outcome without even glancing at your terminal.
Desktop Notifications
Dispatches native desktop notifications via notify-send on Linux and osascript on macOS, displaying the command name and result.
Bulletproof Argument Handling
Quotes and spaces in arguments are preserved completely intact. Commands like vv cp -a "VirtualBox VMs" /dest work out of the box without escaping tricks.
Interactive Config & Command Builder
vv make -j$(nproc)
~/.config/vv/config#!/usr/bin/env bash # ~/.config/vv/config # CPU Nice level (-20 highest priority, 19 lowest) VV_NICENESS="19" # I/O Nice Class (3 = idle, 2 = best-effort, 1 = realtime) VV_IO_NICENESS="3" # Sync dirty filesystem pages after execution (1 = yes, 0 = no) VV_SYNC="1" # Send desktop notifications on completion (1 = yes, 0 = no) VV_NOTIFY="1" # Fallback terminal bell if audio player/sound is unavailable VV_BELL="1" # Audio player is auto-detected (paplay, pw-play, aplay, afplay, mpv, etc.)
Documentation & Reference
Everything you need to install, configure, and customize vv.
1Installation Methods
Automated One-Liner
curl -sL https://raw.githubusercontent.com/joshuacox/vv/refs/heads/master/bootstrapvv.sh | bash
Manual Git Install
git clone https://github.com/joshuacox/vv.git cd vv sudo install -m 0755 vv /usr/local/bin/vv sudo install -m 0644 man/vv.1 /usr/local/share/man/man1/vv.1
CMake Build
cmake . make sudo make install
Nix Flakes
nix profile install github:joshuacox/vv
2Command Line Flags
| Option | Description |
|---|---|
| -h, --help | Displays the usage manual, supported options, and environment variables. |
| -v, --version | Shows current version string (e.g. vv version 0.2.0). |
3Environment Variables Reference
| Variable | Default | Description |
|---|---|---|
| VV_NICENESS | "19" | CPU scheduling niceness passed to nice -n. 19 is lowest CPU priority. |
| VV_IO_NICENESS | "3" | I/O scheduling class passed to ionice -c. 3 is Idle priority. |
| VV_SYNC | "1" | Runs time sync after task completion. Set to 0 to bypass. |
| VV_NOTIFY | "1" | Sends desktop notifications via notify-send or osascript. |
| VV_BELL | "1" | Emits terminal bell (\a) if no audio player or sound file is available. |
| VV_PLAYER | auto | Explicit audio player command (e.g. aplay -q, paplay, afplay). |
| VV_SUCCESS_SOUND | auto | File path to custom sound file for successful command exits (0). |
| VV_FAILURE_SOUND | auto | File path to custom sound file for failed command exits (!= 0). |
ca-pub-8973108060277483Popular Recipes & Use Cases
Real-world patterns where vv makes everyday terminal work seamless.
Heavy Software Compilation
When compiling Rust, C++, or Go projects, compilers use all CPU cores and thrash disk caches. vv ensures your desktop UI remains snappy:
vv cargo build --release vv make -j$(nproc) vv ninja -C build
System Upgrades in Background
Run package updates in another terminal or tmux pane without babysitting it. Get notified immediately when it finishes or needs input:
vv sudo apt-get update && vv sudo apt-get upgrade -y vv sudo pacman -Syu --noconfirm
Large File Backups & Compression
Writing gigabytes of archives triggers kernel page cache writeback. The automatic sync step ensures all data is physically committed to disk:
vv tar -czf backup-2026.tar.gz /home/user/data/ vv rsync -avz --progress /source/ /external_drive/
Fast Network or CPU Tasks (Sync Bypassed)
If your task is purely CPU or network-bound and does not write to disk, you can bypass the disk sync step to alert immediately:
VV_SYNC=0 vv curl -O https://example.com/largefile.iso VV_SYNC=0 vv pytest -q
Frequently Asked Questions
Common questions about vv, audio backends, and terminal environments.
Does vv work over SSH or inside a remote server?
Yes! If audio players are not present on a remote headless server, vv gracefully falls back to emitting the terminal bell character (\a). Most modern SSH terminals and terminal emulators (like iTerm2, Alacritty, GNOME Terminal, Windows Terminal) support visual or audible bell notifications.
How does vv preserve exit codes?
vv executes the wrapped command, immediately traps its exit code (cmd_exit=$?), performs the optional sync and notification routines, and terminates with exit "$cmd_exit". This makes vv completely safe inside shell scripts, Makefiles, and CI/CD pipelines.
Can I customize the sounds to my own audio files?
Absolutely! Set VV_SUCCESS_SOUND="/path/to/winner.ogg" and VV_FAILURE_SOUND="/path/to/error.ogg" in your ~/.config/vv/config file.
ca-pub-8973108060277483