196 lines
4.4 KiB
Markdown
196 lines
4.4 KiB
Markdown
# 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"}
|
|
```
|
|
|
|
You can also set the webhook URL via environment variable:
|
|
|
|
```bash
|
|
export IAMWAITING_WEBHOOK_URL="https://discord.com/api/webhooks/..."
|
|
```
|
|
|
|
## 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
|
|
|
|
## Example Notification
|
|
|
|
```
|
|
⏳ **Claude is waiting** in `my-project`
|
|
📁 Path: `/home/user/repos/my-project`
|
|
🕐 Time: 14:23:45
|
|
```
|
|
|
|
## 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
|