linear-webhook

# Linear Webhook Skill

Enables Linear issue comment @mentions to dispatch tasks to Clawdbot agents.

## How It Works

1. **Comment in Linear:** `@mason implement user authentication` or `@eureka plan Q2 roadmap`
2. **Linear webhook fires** on comment creation
3. **Clawdbot receives webhook** via exposed endpoint
4. **Transform parses payload:**
   - Extracts @mason or @eureka mention
   - Gets issue context (title, description, labels)
   - Prepares task prompt
5. **Routes to agent session:**
   - @mason → `mason` agent (code/implementation)
   - @eureka → `eureka` agent (planning/strategy)
6. **Agent processes task** and returns result
7. **Result posted back** as Linear comment

## Setup

### 1. Configure Clawdbot Webhooks

Add to your `config.json5`:

```json5
{
  hooks: {
    enabled: true,
    token: "your-secret-token-here", // Generate with: openssl rand -base64 32
    path: "/hooks",
    transformsDir: "/home/sven/clawd-mason/skills/linear-webhook",
    mappings: [
      {
        name: "linear",
        match: {
          path: "/linear",
          method: "POST"
        },
        action: "agent",
        transform: {
          module: "./linear-transform.js",
          export: "transformLinearWebhook"
        },
        deliver: false, // Don't auto-deliver to chat - Linear comments handle responses
      }
    ]
  }
}
```

### 2. Expose Webhook Endpoint

Use Cloudflare Tunnel or Tailscale Funnel to make webhook publicly accessible:

**Option A: Cloudflare Tunnel** (Recommended)
```bash
# Install if needed
brew install cloudflared

# Start tunnel (replace with your domain)
cloudflared tunnel --url http://localhost:18789
```

**Option B: Tailscale Funnel**
```bash
# Enable funnel
tailscale funnel 18789
```

Note the public URL (e.g., `https://your-tunnel.trycloudflare.com`)

### 3. Configure Linear Webhook

1. Go to Linear Settings → API → Webhooks
2. Click "Create new webhook"
3. Set URL: `https://your-tunnel.trycloudflare.com/hooks/linear`
4. Add custom header: `x-clawdbot-token: your-secret-token-here`
5. Select events: **Comment → Created**
6. Save webhook

### 4. Test

Comment in a Linear issue:
```
@mason add user authentication to the login page
```

Expected flow:
1. Webhook fires to Clawdbot
2. Mason agent receives task
3. Mason implements or responds
4. Result posted back to Linear issue as comment

## Agent Routing

- **@mason** → Code implementation, debugging, technical tasks
- **@eureka** → Planning, strategy, research, communication
- Other mentions → Ignored (not handled)

## Issue Context Provided

The agent receives:
- Issue title
- Issue description
- Issue labels
- Comment text (the @mention)
- Issue URL
- Commenter name

## Customization

### Add More Agents

Edit `linear-transform.js`:

```javascript
const AGENT_MENTIONS = {
  '@mason': 'mason',
  '@eureka': 'eureka',
  '@designer': 'designer', // Add your own agents
};
```

### Change Response Behavior

Modify `deliver` and `channel` in config:

```json5
{
  deliver: true,
  channel: "telegram",
  to: "1878354815", // Your Telegram chat ID
}
```

This will also send agent responses to Telegram.

## Security

- **Never commit hook token** to version control
- Use environment variables: `CLAWDBOT_HOOK_TOKEN`
- Verify webhook source (Linear's IP ranges if needed)
- Use HTTPS only (Cloudflare Tunnel provides this)

## Troubleshooting

### Webhook not firing
- Check Linear webhook logs (Settings → API → Webhooks → View logs)
- Verify tunnel is running: `curl https://your-tunnel.trycloudflare.com/hooks/linear`
- Check Clawdbot logs: `clawdbot gateway logs`

### Agent not responding
- Check transform is loading: Look for errors in gateway logs
- Verify agent session exists: `clawdbot sessions list`
- Test transform manually: `node linear-transform.js`

### Response not posting to Linear
- Implement Linear API comment posting in transform
- Add Linear API token to config
- See `linear-transform.js` for example

## Linear API Access

To post comments back to Linear, you need a Linear API token:

1. Go to Linear Settings → API → Personal API keys
2. Create new token with `write` scope
3. Add to environment: `CLAWDBOT_LINEAR_API_KEY=lin_api_...`
4. Transform will use this to post responses

## Files

- `SKILL.md` - This documentation
- `linear-transform.js` - Webhook payload parser and agent router
- `linear-api.js` - Linear GraphQL API client (for posting comments)
- `example-payload.json` - Sample Linear webhook payload for testing

## References

- [Clawdbot Webhook Docs](/automation/webhook)
- [Linear Webhooks API](https://developers.linear.app/docs/graphql/webhooks)
- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)