Task Completion Notifier

This skill sends desktop notifications using terminal-notifier to alert the user when tasks are complete.

When to Use This Skill

Use this skill in the following scenarios:

1. User explicitly requests notification – When the user says “notify me when done”, “let me know when this finishes”, etc.
2. Long-running tasks – Jobs that take significant time (builds, deployments, large refactors, test suites)
3. Background tasks – When the user might context-switch while waiting
4. Default behavior – By default, assume all jobs assigned to you will require a notification unless the user specifies otherwise

How to Notify

When a task reaches a terminal state (completed, needs input, or has errors), send a notification using:

terminal-notifier -title "{DESCRIPTION OF JOB}" -message "{STATUS_OF_JOB}" -sound default

The -sound default parameter makes a beeping sound to alert the user audibly.

Status Values

Use one of these status values in the message:

• completed – Task finished successfully
• needs_input – Task requires user input to proceed
• errors – Task encountered errors and cannot proceed

Title Format

The title should be a concise description of the job (3-8 words):

Good examples:

• “Build and Test Suite”
• “API Integration Implementation”
• “Database Migration”
• “Code Refactoring Complete”

Bad examples:

• “Task” (too vague)
• “The implementation of the new authentication system with JWT tokens and refresh token rotation” (too long)

Notification Examples

Successful Completion

terminal-notifier -title "API Integration Implementation" -message "completed" -sound default

Needs User Input

terminal-notifier -title "Database Migration Setup" -message "needs_input" -sound default

Encountered Errors

terminal-notifier -title "Build and Test Suite" -message "errors" -sound default

When to Send Notifications

Send notifications at these key moments:

1. Task completion – When all work is done successfully
2. Blocked on input – When you need user decision or clarification to proceed
3. Critical errors – When errors prevent task completion
4. End of session – When you’ve completed your turn and are waiting for user

When NOT to Send Notifications

Don’t send notifications for:

• Quick tasks (< 30 seconds)
• Intermediate steps of a larger task
• Minor clarifying questions
• Every tool execution
• Tasks where user is actively watching

Best Practices

1. One notification per task – Don’t spam multiple notifications
2. Wait until terminal state – Only notify when task is done or blocked
3. Be specific in title – User should understand what completed
4. Use appropriate status – Accurately reflect the outcome
5. Notify at the end – Send notification as the last action in your turn

Example Workflows

Successful Completion

User: “Implement the new authentication feature and notify me when done”

Assistant steps:

1. Implements authentication feature
2. Adds tests
3. Runs tests (all pass)
4. Sends notification: terminal-notifier -title “Authentication Feature” -message “completed” -sound default

Needs User Input

User: “Set up the database migration”

Assistant steps:

1. Creates migration files
2. Discovers multiple valid approaches for schema design
3. Needs user decision on approach
4. Sends notification: terminal-notifier -title “Database Migration Setup” -message “needs_input” -sound default

Encountered Errors

User: “Run the full test suite and notify me”

Assistant steps:

1. Runs test suite
2. Encounters 5 failing tests
3. Attempts to fix but requires refactoring beyond scope
4. Sends notification: terminal-notifier -title “Test Suite Execution” -message “errors” -sound default

Implementation Notes

Timing

Always send the notification as the last action in your response:

Assistant: I've completed implementing the authentication feature...

[Details of what was done]

All tests are passing. Notifying you now.

[Runs terminal-notifier command]

Error Handling

If terminal-notifier is not installed, gracefully inform the user:

I attempted to send a notification but terminal-notifier is not installed. 
You can install it with: brew install terminal-notifier

Multiple Tasks

For multiple sub-tasks within a larger job, only send ONE notification for the entire job:

❌ Bad – multiple notifications:

- Notification: "User model created"
- Notification: "API endpoint created"  
- Notification: "Tests written"
- Notification: "Authentication complete"

✅ Good – single notification:

- Notification: "Authentication Feature" -message "completed" -sound default

Requirements

This skill requires terminal-notifier to be installed:

brew install terminal-notifier

Check if installed:

which terminal-notifier