iamwaiting/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

iamwaiting is a Babashka CLI tool that sends Discord webhook notifications when Claude Code is waiting for user input. It's designed to be used as a hook in Claude Code to notify users on Discord when their attention is needed.

Architecture

Core Concept

The tool integrates with Claude Code's hook system to send real-time notifications to Discord when Claude is waiting for user input. This allows users to be notified on Discord when they need to return to their terminal/editor.

Code Structure

The entire implementation is a single Babashka script (iamwaiting) with these key functions:

• load-config - Loads webhook URL from config file or environment variable
• send-discord-webhook - Makes HTTP POST request to Discord webhook API
• format-waiting-message - Formats the notification message with project context
• setup-config - Interactive setup wizard for webhook configuration
• test-webhook - Sends a test message to verify configuration
• send-waiting-notification - Main function that sends the notification
• -main - CLI argument parsing and entry point

Configuration

Configuration is stored in ~/.iamwaiting/config.edn with the following structure:

{:webhook-url "https://discord.com/api/webhooks/..."}

Alternatively, the webhook URL can be set via the IAMWAITING_WEBHOOK_URL environment variable.

Installation

Install via bbin (recommended):

bbin install git@git.ajet.fyi:ajet-industries/iamwaiting.git

This installs iamwaiting to ~/.local/bin/iamwaiting (ensure ~/.local/bin is in your PATH).

Common Commands

Note: These examples assume iamwaiting is in your PATH.

Setup

# Initial setup - configure Discord webhook
iamwaiting setup

# Test the webhook configuration
iamwaiting test

Usage

# Send a basic waiting notification
iamwaiting

# Send notification with event data (used by hooks)
iamwaiting '{"cwd": "/path/to/project"}'

Running via Babashka Tasks

bb setup  # Run setup wizard
bb test   # Test webhook
bb run    # Send notification

Hook Integration

To use with Claude Code hooks, add to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [{"type": "command", "command": "iamwaiting"}]
      },
      {
        "matcher": "permission_prompt",
        "hooks": [{"type": "command", "command": "iamwaiting"}]
      }
    ]
  }
}

This configuration triggers notifications for both idle prompts and permission requests.

Important Implementation Details

Discord Webhook API

The tool uses Discord's webhook API which requires:

• Webhook URL from Discord (Server Settings > Integrations > Webhooks)
• POST request with JSON payload containing content, username, and avatar_url
• No authentication required (webhook URL acts as the credential)

Message Format

Notifications include:

• ⏳ Waiting indicator
• 📁 Current working directory / project name
• 🕐 Timestamp (HH:mm:ss format)

Example message:

⏳ **Claude is waiting** in `ajet-industries`
📁 Path: `/home/user/repos/ajet-industries`
🕐 Time: 14:23:45

Error Handling

• Missing configuration prompts user to run ./iamwaiting setup
• Failed webhook requests exit with code 1 and display error message
• Invalid webhook URLs are caught and reported
• Network errors are caught and reported gracefully

Dependencies

Uses Babashka standard libraries:

• babashka.http-client - HTTP requests to Discord API
• babashka.fs - File system operations for config management
• cheshire.core - JSON encoding/decoding
• clojure.string - String manipulation

Development

The script is self-contained with minimal dependencies. To modify:

1. Edit the iamwaiting script directly
2. Test changes using iamwaiting test (or ./iamwaiting test if running from the repo directory)
3. The script is executable via shebang #!/usr/bin/env bb

Security Considerations

• Webhook URL should be kept secret (it allows posting to your Discord channel)
• Config file at ~/.iamwaiting/config.edn has standard file permissions
• No sensitive data is sent in notifications beyond directory paths
• Webhook URLs are never logged or displayed (except during setup)

Context: Monorepo Usage

This tool is part of the ajet-industries monorepo and can be used with any project. It's particularly useful when working on long-running tasks where Claude may need user input while the user is away from their terminal.

Other tools in the monorepo:

• commitly/ - Multi-repo commit and push tool
• service-manager/ - Microservice orchestration
• www/ - Dashboard website
• gateway/ - Nginx reverse proxy

Future Enhancements

Possible improvements:

• Support for multiple notification channels
• Customizable message templates
• Integration with other notification services (Slack, Telegram, etc.)
• Retry logic for failed webhook requests
• Rate limiting to avoid spam