task-banner — Claude Code skill: desktop completion banner
task-banner displays a persistent macOS desktop banner when Claude Code finishes a task, with a one-line summary of what was done. Works even when Notification Center silently drops CLI notifications.
MIT 126 installs ★ 750 updated 2026-10-21
npx skills add OpenClaudia/openclaudia-skills --skill task-banner -a claude-codeWhat task-banner does
The skill draws an overlay window using JXA scripting (mac-overlay.js), bypassing macOS Notification Center permission requirements. It reads a message from /tmp/claude-banner-msg — which you populate from your agent instructions after each task — and falls back to 'Task done' if the file is absent. Setup involves copying mac-overlay.js to ~/.claude/scripts/, merging a Stop hook into ~/.claude/settings.json, and optionally adding a write command to your agent instructions.
Toggling is stateless: create ~/.claude/banner.off to mute, delete it to unmute. The hook consumes the message file even while muted, so no stale summary appears later. Colors, alignment, and dismiss time are configurable; recent macOS versions may require a hardcoded alignment value to compensate for AppKit constant changes.
macOS only.
What it helps with
- receive desktop notifications when Claude Code finishes, even if system notifications fail
- see at a glance what task was just completed
- mute notifications without reinstalling or editing config
- keep a persistent on-screen summary that survives window focus changes
Example prompts for the agent
- Set up task-banner and remind me with a banner when you finish each task
- Mute the banner while I work in other applications
- Show me in the banner what file you fixed or which command you ran
How to install task-banner
1Skills CLI (Vercel)
npx skills add OpenClaudia/openclaudia-skills --skill task-banner -a claude-code2Manually: put the files in place
~/.claude/skills/task-banner/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/task-banner/
1Skills CLI (Vercel)
npx skills add OpenClaudia/openclaudia-skills --skill task-banner -a codex2Manually: put the files in place
.agents/skills/task-banner/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add OpenClaudia/openclaudia-skills --skill task-banner -a cursor2Manually: put the files in place
.cursor/skills/task-banner/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install OpenClaudia/openclaudia-skills skills/task-banner2Manually: put the files in place
.github/skills/task-banner/SKILL.md1Skills CLI (Vercel)
npx skills add OpenClaudia/openclaudia-skills --skill task-banner -a gemini-cli2Platform CLI
gemini skills install https://github.com/OpenClaudia/openclaudia-skills --path skills/task-bannerManually: put the files in place
.devin/skills/task-banner/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add OpenClaudia/openclaudia-skills --skill task-banner -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about task-banner
How do I install task-banner in Claude Code?
Run npx skills add OpenClaudia/openclaudia-skills --skill task-banner -a claude-code, then read ~/.claude/skills/task-banner/SKILL.md for the full hook setup and script installation steps.
What does task-banner do?
Shows an overlay banner on your macOS desktop each time Claude Code completes a task. The banner displays one line of text describing what was done and dismisses on click or after a set duration.
Can I disable the banner without reinstalling?
Yes: run touch ~/.claude/banner.off to mute, or rm -f ~/.claude/banner.off to unmute. No config changes needed.
Source text
SKILL.md · MIT
---
name: task-banner
description: Set up (or toggle) a macOS desktop banner that appears whenever Claude Code finishes a task, showing a one-line summary of what was done. Use when the user says "notify me when Claude is done", "desktop notification on completion", "set up the task banner", "mute the banner", or "unmute the banner".
---
# task-banner
Show a large, always-on-top desktop banner when Claude Code finishes a turn — with a one-line summary of what was actually completed. Works even when macOS Notification Center silently drops `osascript display notification` calls (a common problem: the CLI has no Notification Center registration, so the command exits 0 but nothing shows).
The banner is a borderless Cocoa overlay window drawn by `mac-overlay.js` (a JXA script adapted from [peon-ping](https://github.com/PeonPing/peon-ping)), so no notification permissions are needed.
## Requirements
- macOS (the overlay uses Cocoa via JXA / `osascript -l JavaScript`)
- Claude Code with hooks support
## Setup
1. Copy `mac-overlay.js` from this skill directory to `~/.claude/scripts/mac-overlay.js`.
2. Merge a `Stop` hook into `~/.claude/settings.json` (read the file first and preserve existing hooks):
```json
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "m=$(cat /tmp/claude-banner-msg 2>/dev/null); rm -f /tmp/claude-banner-msg; [ -f ~/.claude/banner.off ] || osascript -l JavaScript ~/.claude/scripts/mac-overlay.js \"${m:-Task done}\" blue \"\" 0 4 2>/dev/null || true",
"async": true
}
]
}
]
}
}
```
3. To make the banner show *what* was finished (instead of the generic "Task done"), add this to your global agent instructions file (`~/.claude/CLAUDE.md` or `AGENTS.md`):
> After finishing each task, write a short summary of what was completed to `/tmp/claude-banner-msg` (e.g. `printf 'Typecheck fixed and committed' > /tmp/claude-banner-msg`). Identify the actual task; never use a generic "task done".
The Stop hook displays the message and deletes the file. If the file is absent, it falls back to "Task done".
## Toggle (mute / unmute)
The hook checks a sentinel file — no config editing needed:
```bash
touch ~/.claude/banner.off # mute the banner
rm -f ~/.claude/banner.off # unmute
```
When the user asks to mute/unmute the banner, run the matching command and report the resulting state.
## How it works / notes
- `mac-overlay.js <message> <color> <icon> <slot> <dismiss_seconds>` — color is `blue`/`yellow`/`red`, dismiss `0` means persistent-until-click.
- The hook consumes `/tmp/claude-banner-msg` even while muted, so no stale summary pops up later when unmuted.
- On recent macOS the JXA bridge constant `NSTextAlignmentCenter` evaluates to the legacy AppKit value (2), which the unified runtime treats as right-aligned — the bundled script hardcodes alignment `1` (center) to compensate.
- `/tmp/claude-banner-msg` is shared across parallel Claude sessions; if two finish in the same instant one banner may show the other's summary. Use a per-session file path if that ever matters.
© OpenClaudia · MIT · OpenClaudia/openclaudia-skills