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

:

{
  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)

# Install if needed
brew install cloudflared

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

Option B: Tailscale Funnel

# 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

:

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

Change Response Behavior

Modify

deliver

and

channel

in config:

{
  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
• Linear Webhooks API
• Cloudflare Tunnel