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

# Linear Webhook Skill

Enables @mason and @eureka mentions in Linear issue comments to dispatch tasks to Clawdbot agents.

## Quick Start

### 1. Install Dependencies
```bash
# None required - uses Node.js built-ins
```

### 2. Configure Clawdbot

Add this to your Clawdbot config (`.clawd/config.json5`):

```json5
{
  hooks: {
    enabled: true,
    token: process.env.CLAWDBOT_HOOK_TOKEN,
    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,
      }
    ]
  }
}
```

### 3. Set Environment Variables

```bash
# Generate hook token
export CLAWDBOT_HOOK_TOKEN=$(openssl rand -base64 32)

# Get Linear API key from: https://linear.app/settings/api
export LINEAR_API_KEY="lin_api_your_key_here"
```

### 4. Expose Webhook Endpoint

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

# Start tunnel
cloudflared tunnel --url http://localhost:18789

# Note the public URL (e.g., https://abc-123.trycloudflare.com)
```

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

### 5. Configure Linear Webhook

1. Go to **Linear Settings** → **API** → **Webhooks**
2. Click "Create new webhook"
3. **URL:** `https://your-tunnel-url.trycloudflare.com/hooks/linear`
4. **Custom Header:** 
   - Name: `x-clawdbot-token`
   - Value: `your-CLAWDBOT_HOOK_TOKEN`
5. **Events:** Select **Comment → Created**
6. **Save**

### 6. Test

Comment in a Linear issue:
```
@mason implement OAuth2 authentication
```

Check Clawdbot logs:
```bash
clawdbot gateway logs
```

## Usage

### Mention Agents

- **@mason** - Code implementation, debugging, technical tasks
- **@eureka** - Planning, strategy, research, communication

### Example Comments

```
@mason add user au...