iterm-notify

Name: iterm-notify
Availability: InStock
Author: harnessprotocol

Send macOS desktop notifications and manage iTerm2 badges for Claude Code lifecycle events.

9|2|Updated Mar 7, 2026

Search Tags:#claude code #hooks #notifications #macos #iterm2 #terminal-notifier #badge management

Ready to run

npx skills add https://github.com/harnessprotocol/harness-kit --skill iterm-notify

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: iterm-notify
Source: https://github.com/harnessprotocol/harness-kit/tree/main/plugins/iterm-notify/skills/iterm-notify
Command: npx skills add https://github.com/harnessprotocol/harness-kit --skill iterm-notify

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires terminal-notifier, jq, and includes scripts (resource) components.

What problem does it solve?

It helps you notice when Claude Code needs your attention and when a task is finished, without constantly watching the iTerm2 session.

Core Features & Use Cases

iTerm2 badge on Notification: Bounces the dock icon, sets an iTerm2 badge to indicate activity, and reads a configurable label from a local file to show context like the current project.
macOS desktop notification on Notification: Sends a clickable notification using terminal-notifier that focuses the iTerm2 window running Claude.
Badge cleared on Stop: Resets the iTerm2 badge when Claude completes work.

Quick Start

Wire the plugin hook into your ~/.claude/settings.json so the Notification and Stop events both call the provided notify.sh script.

Frequently Asked Questions about iterm-notify

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I get macOS desktop notifications when Claude Code finishes a task?▼

You can get macOS desktop notifications when Claude Code finishes a task by wiring the notify.sh script into the Stop hook in your ~/.claude/settings.json, which sends a terminal-notifier alert when work is complete.

Can I display an iTerm2 badge showing project context during Claude Code sessions?▼

Yes, you can display an iTerm2 badge during Claude Code sessions by configuring the Notification hook to call notify.sh, which reads a local file to show context like the current project on your terminal badge.

What dependencies do I need to set up iTerm2 badge management for Claude Code hooks?▼

To set up iTerm2 badge management for Claude Code hooks, you need terminal-notifier for macOS alerts and jq for processing hook data, plus the notify.sh script mapped in your settings.json.

How do I configure Claude Code hooks to bounce the dock icon when attention is needed?▼

Configure the Claude Code Notification hook in your ~/.claude/settings.json to call notify.sh, which bounces the macOS dock icon and sends a clickable alert to focus the iTerm2 window when attention is needed.

Does the iTerm2 badge automatically clear when Claude Code stops running?▼

Yes, the iTerm2 badge automatically clears when Claude Code stops running by mapping the Stop lifecycle event to the notify.sh script, which resets the badge upon task completion.

Why do I need terminal-notifier for Claude Code notifications on macOS?▼

You need terminal-notifier for Claude Code notifications on macOS because it provides the native system capability to send clickable desktop alerts that focus your iTerm2 window when Claude requires attention.