iamwaiting/README.md

# iamwaiting

Send Discord notifications when Claude Code is waiting for your input.

## What is this?

`iamwaiting` is a lightweight CLI tool that integrates with Claude Code's hook system to send you Discord notifications when Claude needs your attention. Perfect for long-running tasks where you step away from your terminal.

## Quick Start

### 1. Install

#### Using bbin (Recommended)

Install directly from Gitea using SSH:

```bash
# Install from your Gitea repository via SSH
bbin install git@git.ajet.fyi:ajet-industries/iamwaiting.git

# Install a specific version using a git tag
bbin install git@git.ajet.fyi:ajet-industries/iamwaiting.git --git/tag v1.0.0

# Install the latest commit
bbin install git@git.ajet.fyi:ajet-industries/iamwaiting.git --latest-sha
```

This will install `iamwaiting` to `~/.local/bin/iamwaiting` (make sure `~/.local/bin` is in your PATH).

**Note:** Requires [bbin](https://github.com/babashka/bbin) to be installed first:
```bash
bash < <(curl -s https://raw.githubusercontent.com/babashka/bbin/main/bbin)
```

#### Manual Installation

Requires [Babashka](https://babashka.org/):

```bash
# macOS
brew install borkdude/brew/babashka

# Linux
bash <(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)
```

Then clone and symlink:

```bash
# Clone the repository
git clone git@git.ajet.fyi:ajet-industries/iamwaiting.git
cd iamwaiting

# Make the script executable
chmod +x iamwaiting

# Symlink to a directory in your PATH
ln -s $(pwd)/iamwaiting ~/.local/bin/iamwaiting
```

### 2. Set Up Discord Webhook

```bash
iamwaiting setup
```

Follow the prompts to enter your Discord webhook URL. Get a webhook URL from:
Discord Server → Server Settings → Integrations → Webhooks → New Webhook

### 3. Test It

```bash
iamwaiting test
```

You should see a test message in your Discord channel!

### 4. Configure Claude Code Hook

Add to `~/.claude/settings.json`:

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

## Usage

**Note:** These examples assume `iamwaiting` is in your PATH (e.g., installed via bbin or symlinked).

### Manual Testing

```bash
# Send a test notification
iamwaiting test

# Send a waiting notification
iamwaiting

# Send notification with custom data
iamwaiting '{"cwd": "/path/to/project"}'
```

### Babashka Tasks (if running from repository directory)

```bash
bb setup  # Run setup wizard
bb test   # Send test message
bb run    # Send waiting notification
```

## Configuration

Configuration is stored in `~/.iamwaiting/config.edn`:

```clojure
{:webhook-url "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
 :user-id "123456789012345678"  ; Optional: for @mentions
 :toggles {:idle-prompt true
           :permission-prompt true
           :permission-prompt-ping true}}
```

You can also set the webhook URL via environment variable:

```bash
export IAMWAITING_WEBHOOK_URL="https://discord.com/api/webhooks/..."
export IAMWAITING_USER_ID="123456789012345678"  # Optional
```

### Advanced Configuration

Control which notifications you receive using toggles:

```bash
# Show current toggle status
iamwaiting toggle status

# Toggle notification types on/off
iamwaiting toggle idle-prompt on|off
iamwaiting toggle permission-prompt on|off

# Control @mentions on permission prompts
iamwaiting toggle permission-prompt-ping on|off
```

**Use cases:**
- **Focus time:** Disable pings but keep notifications (`permission-prompt-ping off`)
- **Critical only:** Only notify on permission prompts (`idle-prompt off`)
- **Silent mode:** Disable all notifications (both toggles `off`)

## How It Works

When Claude Code is waiting for user input, the `agent-waiting-for-user` hook is triggered, which:

1. Runs the `iamwaiting` command
2. Reads the Discord webhook URL from config
3. Formats a message with project context (name, path, timestamp)
4. Sends an HTTP POST to Discord's webhook API
5. Returns success/failure status

The notification appears in your Discord channel with:
- ⏳ Waiting indicator
- 📁 Project name and path
- 🕐 Timestamp
- @mention (if configured and enabled for permission prompts)

## Example Notifications

**Idle prompt (standard notification):**
```
⏳ **Claude is waiting** in `my-project`
📁 Path: `/home/user/repos/my-project`
🕐 Time: 14:23:45
```

**Permission prompt with ping enabled:**
```
<@123456789012345678> ⏳ **Claude is waiting** in `my-project`
📁 Path: `/home/user/repos/my-project`
🕐 Time: 14:23:45
📢 Type: `permission_prompt`
```

**Permission prompt with ping disabled:**
```
⏳ **Claude is waiting** in `my-project`
📁 Path: `/home/user/repos/my-project`
🕐 Time: 14:23:45
📢 Type: `permission_prompt`
```

## Troubleshooting

**"No webhook URL configured"**
- Run `iamwaiting setup` to configure your webhook

**"Failed to send message"**
- Check your webhook URL is correct
- Verify the webhook hasn't been deleted in Discord
- Check your internet connection

**Hook not triggering**
- Verify `settings.json` syntax is correct
- Ensure `iamwaiting` is in your PATH
- Check Claude Code hooks documentation

## Security

- Keep your webhook URL secret (treat it like a password)
- Config file has standard Unix permissions (readable only by you)
- Only directory paths are sent in notifications (no code or sensitive data)

## Requirements

- Babashka (bb command)
- Discord webhook URL
- Internet connection

## License

Part of the ajet-industries monorepo.

## Related Tools

- [commitly](../commitly) - Multi-repo commit and push tool
- [service-manager](../service-manager) - Microservice orchestration platform