Gbam
"When your code finally works, you need to hear it."
Gbam plays a satisfying Nigerian "Gbam!" sound effect every time your tests pass, builds succeed, or debug sessions finish. Because success should feel good.
Features
- 🔊 Instant sound on every success — tasks, builds, debug sessions
- 💥 Full status bar flash — the entire bar lights up green on success
- ⏱️ Cooldown protection — Configurable debounce prevents sound spam
- 💻 Cross-platform — works on macOS, Linux, and Windows with no installs
- 🔘 Status bar button — click
💥 Gbam to test sound and flash anytime
- ⚙️ Fully configurable — Customize sounds, colors, cooldown, and trigger patterns
- 🎵 Custom sounds — Use your own WAV files for the success sound
- 🎯 Smart detection — Configurable task patterns, exclude patterns, and strict mode
How It Triggers
Gbam fires automatically when:
- A task completes successfully (exit code 0) with a name matching your configured patterns (default:
build, test, dev, start, run, compile, deploy)
- A debug session ends (launch-type sessions only, configurable to include attach-type)
You can also trigger it manually by clicking 💥 Gbam in the status bar or running "Test Gbam Sound" from the Command Palette (Ctrl+Shift+P).
Configuration
All settings are available in VS Code Settings under Gbam:
| Setting |
Default |
Description |
gbam.cooldownMs |
3000 |
Cooldown period between sounds in milliseconds (prevents sound spam) |
gbam.flashDurationMs |
600 |
Status bar flash duration in milliseconds |
gbam.flashColorBg |
#23d18b |
Status bar flash background color (hex format) |
gbam.flashColorFg |
#000000 |
Status bar flash foreground color (hex format) |
gbam.taskPatterns |
build, test, dev, start, run, compile, deploy |
Task name patterns that trigger Gbam (matches as substrings) |
gbam.taskExcludePatterns |
[] |
Task name patterns to exclude from triggering Gbam |
gbam.enableOnLaunch |
true |
Enable Gbam automatically when VS Code starts |
gbam.includeAttachDebugSessions |
false |
Trigger Gbam when attach-type debug sessions end |
gbam.requireExitCodeZero |
true |
Only trigger Gbam when tasks exit with code 0 (success) |
gbam.strictTaskDetection |
false |
Only trigger if task definition has 'isBuild' or 'isTest' property set to true |
gbam.customSoundPath |
"" |
Absolute path to a custom WAV sound file. If empty, uses the built-in Gbam sound |
Example Configuration
{
"gbam.cooldownMs": 2000,
"gbam.flashColorBg": "#ff6b6b",
"gbam.taskPatterns": ["build", "test", "lint"],
"gbam.taskExcludePatterns": ["watch"],
"gbam.customSoundPath": "/path/to/your/custom-sound.wav"
}
Requirements
- VS Code 1.90.0 or higher
- No npm packages or external installs required
Audio is handled by built-in OS tools:
| Platform |
Tool used |
Ships with OS? |
| macOS |
afplay |
✅ Always |
| Linux |
paplay → aplay → ffplay (first found) |
✅ Most distros |
| Windows |
wscript.exe + WMPlayer (VBScript) |
✅ Since Windows 98 |
Commands
All commands are available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
| Command |
Description |
Gbam: Test Gbam Sound |
Trigger sound and flash manually |
Gbam: Enable Gbam |
Re-enable after disabling |
Gbam: Disable Gbam |
Silence Gbam without uninstalling |
Known Limitations
- Task success detection is based on exit codes — Gbam treats any task that exits with code
0 as a success. It cannot distinguish between a true successful run and cases where a process exits cleanly but was manually stopped or did not complete its intended work. Use strictTaskDetection for more accurate detection.
- Debug session detection is heuristic-based — VS Code does not provide an exit code for debug sessions. Gbam triggers when a
launch-type session ends, but cannot determine whether it ended successfully or was stopped manually.
- Linux audio requires at least one of
paplay, aplay, or ffplay to be installed. Most desktop Linux distros include one by default
- Custom sounds must be WAV format — Only WAV files are supported for custom sounds
Release Notes
0.1.0
Major improvements:
- Full configuration support — All settings are now customizable via VS Code settings
- Custom sound support — Use your own WAV files for the success sound
- Improved task detection — Added exclude patterns, strict mode, and configurable exit code requirements
- Attach debug session support — Optional support for attach-type debug sessions
- Automatic environment detection — No more manual code changes for production builds
- Test coverage — Added unit tests for core functionality
- Better logging — Enhanced output channel logging for debugging
0.0.2
Post-release updates:
0.0.1
Initial release:
- Task success detection (
build, test, dev, start, run, compile, deploy)
- Debug session termination detection
- Full status bar green flash on success
- Manual test via status bar click or Command Palette
- Cooldown-aware click handler (shows remaining time if clicked during cooldown)
- Cross-platform audio with automatic fallback chain
Development
git clone https://github.com/Richard-Raph/gbam.git
cd gbam
npm install
npm run compile
# Press F5 in VS Code to launch the Extension Development Host
To run tests:
npm run compile
npm test
To test manually inside the dev host, click 💥 Gbam in the status bar or run "Test Gbam Sound" from the Command Palette.
To package for production:
npm run compile
vsce package
Contributing
Issues and pull requests are welcome. Please see CONTRIBUTING.md for guidelines.
Security
For security vulnerabilities, please see SECURITY.md.
License
MIT License - see LICENSE for details.
