Notifications

Overview

Agentastic provides a two-way notification system that keeps you informed about your AI agents' status. When an agent is waiting for input or has completed a task, you'll know immediately—even if you're working in another application.

Agent Waiting Indicator

When an AI agent (like Claude Code) is waiting for your input, Agentastic displays an orange indicator badge next to the agent in the sidebar. This helps you quickly identify which agents need attention.

How It Works

Agentastic monitors a special file at .agentastic/waiting in your workspace. When this file exists and contains content, the waiting indicator appears.

Creating the waiting indicator:

echo "waiting" > .agentastic/waiting

Clearing the waiting indicator:

rm .agentastic/waiting

Claude Code automatically manages this file—creating it when waiting for input and removing it when you respond.

Terminal Bell Notifications

When a long-running task completes, agents can send a terminal bell notification using the standard escape sequence:

echo "\a"

or equivalently:

printf '\a'

This triggers a macOS notification, alerting you that the task is complete even if Agentastic isn't in the foreground.

Claude Code Hook Integration

Claude Code supports hooks that run shell commands on specific events. You can configure these to enhance your notification workflow.

Setting Up Completion Notifications

Create or edit your Claude Code settings file at ~/.claude/settings.json:

{
  "hooks": {
    "stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '\a'"
          }
        ]
      }
    ]
  }
}

This configuration runs echo '\a' whenever Claude Code stops responding, sending you a notification.

Hook Events

Claude Code supports several hook events:

Event	Description
stop	Triggered when Claude stops and waits for input
notification	Triggered for explicit notifications
preToolUse	Triggered before a tool is used
postToolUse	Triggered after a tool is used

Example: Notification with Sound

For a more noticeable alert, combine the terminal bell with macOS's say command:

{
  "hooks": {
    "stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '\a' && say 'Claude is ready'"
          }
        ]
      }
    ]
  }
}

Example: Custom Notification Script

Create a custom notification script for more control:

#!/bin/bash
# ~/.local/bin/claude-notify.sh

# Terminal bell for Agentastic
echo '\a'

# macOS notification center
osascript -e 'display notification "Claude is waiting for input" with title "Agentastic"'

Then reference it in your settings:

{
  "hooks": {
    "stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/claude-notify.sh"
          }
        ]
      }
    ]
  }
}

Workflow Tips

• Multiple agents: The waiting indicator helps you track which of your many agents need attention
• Background work: Let agents run complex tasks while you work elsewhere—notifications bring you back when needed
• Audio cues: Add say commands to hooks for audio notifications
• Focus modes: Configure macOS Focus modes to allow Agentastic notifications during work hours

Troubleshooting

Waiting indicator not appearing

1. Ensure the agent is running Claude Code (or another compatible tool)
2. Check that the workspace has a .agentastic/ directory
3. Verify file permissions allow creating files in the workspace

Terminal bell not working

1. Check System Settings > Notifications > Agentastic to ensure notifications are enabled
2. Verify your terminal backend supports bell notifications (Ghostty recommended)
3. Test with echo '\a' in a terminal to confirm it works

Hooks not triggering

1. Verify your ~/.claude/settings.json syntax is valid JSON
2. Check that Claude Code has reloaded settings (restart the session)
3. Test hooks manually to ensure commands work