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

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.

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