I Built My First VS Code Extension — A Sound Alert for Failed Terminal Commands

#vscode #typescript #opensource #devtools

The Problem

I run a lot of long terminal commands — builds, test suites, Docker operations, package installs. The habit I'd developed was: start the command, switch to another window to do something else, come back later.

The problem is "later" is often too late. The command failed at minute two. I didn't notice. I lost time I didn't need to lose.

I wanted something simple: just make a sound when it fails.

What I Built

FAAH Terminal Alert is a VS Code extension that monitors your integrated terminal and plays an audio notification the moment a command exits with a non-zero status code.

That's the core of it. One focused thing.

Features:

Detects failed terminal commands (non-zero exit codes)
Works on Windows, macOS, and Linux
Toggle on/off from the status bar or keyboard shortcut
Configurable cooldown between alerts (default 1000ms)
Test sound button so you can confirm it's working
Debug mode with Output panel logging
Completely idle when disabled — no background activity

How It Works

The extension hooks into VS Code's onDidExecuteTerminalCommand terminal event API. When any command completes in the integrated terminal, VS Code fires this event with the exit code. If the exit code is non-zero, the extension triggers an audio alert using the OS's built-in audio capabilities.

One Known Limitation

Git Bash doesn't reliably report exit codes to VS Code's terminal API. This is a limitation of how Git Bash integrates with VS Code, not something the extension can work around. PowerShell and standard bash work correctly.

I mention this upfront because it's better to know before installing than to assume it's broken.

What I Learned Building This

Building the extension itself was straightforward. The VS Code extension API is well-documented and the TypeScript scaffolding gets you started quickly.

The more interesting part was understanding the boundaries of what VS Code's terminal API actually exposes. The onDidExecuteTerminalCommand event is relatively recent in the API — older approaches required shell integration hacks or parsing terminal output, both of which are fragile. Using the official event means the extension stays stable across VS Code updates without maintenance.

The other thing I didn't expect: how much the packaging and distribution side of a VS Code extension involves. Between .vsixmanifest, the extension bundle, and what actually ends up inside the .vsix file, there's more to think about than just writing the TypeScript.