DevContainer Host Notifier

This VS Code extension allows you to trigger host OS notifications from within a Dev Container. This is ideal for receiving alerts when long-running background tasks (builds, tests, hooks) complete.

Use Cases

🤖 Claude Code & AI Agents

Perfect for using Claude Code in Dev Containers. You can set up a notification hook to alert your host machine when the agent completes a task or requires input.

Reference: Claude Code Dev Container Guide

⏳ Long-running Commands

Don't stare at the terminal waiting for builds, tests, or installations to finish. Chain a notification command to let you know when it's done.

# Example
npm install && echo '{"message": "Ready to code!"}' > .devcontainer/host-notifier.json

🚨 Custom Script Alerts

Trigger alerts from your internal scripts or watchers when specific events occur (e.g., database migration finished, server crashed).

Platform Support

OS	Status	Notes
macOS	✅ Verified	Verified on macOS Tahoe 26.2. Uses native AppleScript for reliable notifications.
Windows	⚠️ Experimental	Implemented using node-notifier (snoreToast) but not verified (Author lacks environment). Contributions welcome!
Linux	⚠️ Experimental	Implemented using notify-send but not verified (Author lacks environment). Contributions welcome!

Quick Start

1. Enable and Configure

This extension is disabled by default. Add the following to your VS Code settings (.vscode/settings.json):

{
    "hostNotifier.enable": true
}

2. Verify Permissions (macOS)

On macOS, this extension uses AppleScript. You must allow "Script Editor" to show notifications:

• Go to System Settings > Notifications.
• Find Script Editor (or osascript) in the list.
• Ensure "Allow Notifications" is ON.

3. Usage

This extension watches for changes in .devcontainer/host-notifier.json inside your workspace. To trigger a notification, simply write a JSON object to this file from anywhere (shell, script, application).

Recommended Setup

Since host-notifier.json is a temporary trigger file, you should strictly git-ignore it.

Add the following to your .gitignore:

.devcontainer/host-notifier.json

2. Basic Usage

Run the following command in your Dev Container terminal:

# Ensure the directory exists (it usually does)
mkdir -p .devcontainer

# Write the notification payload
echo '{"message": "Hello from Container", "title": "My App"}' > .devcontainer/host-notifier.json

The extension on the host will detect this file change and display the notification instantly.

Configuration

You can customize the extension behavior by adding the following settings to your .vscode/settings.json or .devcontainer/devcontainer.json.

Setting	Type	Default	Description
hostNotifier.enable	boolean	false	Enable or disable the extension. Must be set to true to use.
hostNotifier.watchPath	string	.devcontainer/host-notifier.json	Path to the file to watch for notification triggers (relative to workspace root).
hostNotifier.defaultTitle	string	null	Default notification title. If not set, the workspace name is used.
hostNotifier.enableSound	boolean	true	Enable or disable notification sounds globally. Note: If set to false, this overrides any sound setting in the JSON payload (master switch).
hostNotifier.debounceInterval	integer	200	Debounce interval in milliseconds to prevent duplicate notifications.

Tips: Simplify with a Shell Function

To make this easier to use on a daily basis, you can define a helper function in your shell configuration (e.g., ~/.bashrc or ~/.zshrc inside the container).

# Add this to your ~/.bashrc
notify-host() {
    mkdir -p .devcontainer
    # Use simple redirection
    echo "{\"message\": \"${1:-Done}\", \"title\": \"${2:-Dev Container}\"}" > .devcontainer/host-notifier.json
}

Usage:

notify-host "Build Finished!"
npm run build && notify-host "Success" || notify-host "Failed"

How it works

1. The extension runs on the Host (UI side).
2. It watches **/.devcontainer/host-notifier.json in the workspace.
3. When you write to this file from the Container (which shares the volume), the Host extension detects the change.
4. The extension reads the JSON content and triggers a native OS notification.

Requirements

• VS Code ^1.80.0
• extensionKind set to ["ui"] (handled automatically).