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:

```clojure
{: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):

```bash
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

```bash
# Initial setup - configure Discord webhook
iamwaiting setup

# Test the webhook configuration
iamwaiting test
```

### Usage

```bash
# Send a basic waiting notification
iamwaiting

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

### Running via Babashka Tasks

```bash
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`:

```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