{"skill":{"slug":"linear-webhook","displayName":"Linear Webhook","summary":"Comment @mason or @eureka in Linear issues to dispatch tasks to agents. Webhook receives Linear comments and routes to correct agent.","description":"---\nname: linear-webhook\ndescription: \"Comment @mason or @eureka in Linear issues to dispatch tasks to agents. Webhook receives Linear comments and routes to correct agent.\"\n---\n\n# Linear Webhook Skill\n\nEnables Linear issue comment @mentions to dispatch tasks to Clawdbot agents.\n\n## How It Works\n\n1. **Comment in Linear:** `@mason implement user authentication` or `@eureka plan Q2 roadmap`\n2. **Linear webhook fires** on comment creation\n3. **Clawdbot receives webhook** via exposed endpoint\n4. **Transform parses payload:**\n   - Extracts @mason or @eureka mention\n   - Gets issue context (title, description, labels)\n   - Prepares task prompt\n5. **Routes to agent session:**\n   - @mason → `mason` agent (code/implementation)\n   - @eureka → `eureka` agent (planning/strategy)\n6. **Agent processes task** and returns result\n7. **Result posted back** as Linear comment\n\n## Setup\n\n### 1. Configure Clawdbot Webhooks\n\nAdd to your `config.json5`:\n\n```json5\n{\n  hooks: {\n    enabled: true,\n    token: \"your-secret-token-here\", // Generate with: openssl rand -base64 32\n    path: \"/hooks\",\n    transformsDir: \"/home/sven/clawd-mason/skills/linear-webhook\",\n    mappings: [\n      {\n        name: \"linear\",\n        match: {\n          path: \"/linear\",\n          method: \"POST\"\n        },\n        action: \"agent\",\n        transform: {\n          module: \"./linear-transform.js\",\n          export: \"transformLinearWebhook\"\n        },\n        deliver: false, // Don't auto-deliver to chat - Linear comments handle responses\n      }\n    ]\n  }\n}\n```\n\n### 2. Expose Webhook Endpoint\n\nUse Cloudflare Tunnel or Tailscale Funnel to make webhook publicly accessible:\n\n**Option A: Cloudflare Tunnel** (Recommended)\n```bash\n# Install if needed\nbrew install cloudflared\n\n# Start tunnel (replace with your domain)\ncloudflared tunnel --url http://localhost:18789\n```\n\n**Option B: Tailscale Funnel**\n```bash\n# Enable funnel\ntailscale funnel 18789\n```\n\nNote the public URL (e.g., `https://your-tunnel.trycloudflare.com`)\n\n### 3. Configure Linear Webhook\n\n1. Go to Linear Settings → API → Webhooks\n2. Click \"Create new webhook\"\n3. Set URL: `https://your-tunnel.trycloudflare.com/hooks/linear`\n4. Add custom header: `x-clawdbot-token: your-secret-token-here`\n5. Select events: **Comment → Created**\n6. Save webhook\n\n### 4. Test\n\nComment in a Linear issue:\n```\n@mason add user authentication to the login page\n```\n\nExpected flow:\n1. Webhook fires to Clawdbot\n2. Mason agent receives task\n3. Mason implements or responds\n4. Result posted back to Linear issue as comment\n\n## Agent Routing\n\n- **@mason** → Code implementation, debugging, technical tasks\n- **@eureka** → Planning, strategy, research, communication\n- Other mentions → Ignored (not handled)\n\n## Issue Context Provided\n\nThe agent receives:\n- Issue title\n- Issue description\n- Issue labels\n- Comment text (the @mention)\n- Issue URL\n- Commenter name\n\n## Customization\n\n### Add More Agents\n\nEdit `linear-transform.js`:\n\n```javascript\nconst AGENT_MENTIONS = {\n  '@mason': 'mason',\n  '@eureka': 'eureka',\n  '@designer': 'designer', // Add your own agents\n};\n```\n\n### Change Response Behavior\n\nModify `deliver` and `channel` in config:\n\n```json5\n{\n  deliver: true,\n  channel: \"telegram\",\n  to: \"1878354815\", // Your Telegram chat ID\n}\n```\n\nThis will also send agent responses to Telegram.\n\n## Security\n\n- **Never commit hook token** to version control\n- Use environment variables: `CLAWDBOT_HOOK_TOKEN`\n- Verify webhook source (Linear's IP ranges if needed)\n- Use HTTPS only (Cloudflare Tunnel provides this)\n\n## Troubleshooting\n\n### Webhook not firing\n- Check Linear webhook logs (Settings → API → Webhooks → View logs)\n- Verify tunnel is running: `curl https://your-tunnel.trycloudflare.com/hooks/linear`\n- Check Clawdbot logs: `clawdbot gateway logs`\n\n### Agent not responding\n- Check transform is loading: Look for errors in gateway logs\n- Verify agent session exists: `clawdbot sessions list`\n- Test transform manually: `node linear-transform.js`\n\n### Response not posting to Linear\n- Implement Linear API comment posting in transform\n- Add Linear API token to config\n- See `linear-transform.js` for example\n\n## Linear API Access\n\nTo post comments back to Linear, you need a Linear API token:\n\n1. Go to Linear Settings → API → Personal API keys\n2. Create new token with `write` scope\n3. Add to environment: `CLAWDBOT_LINEAR_API_KEY=lin_api_...`\n4. Transform will use this to post responses\n\n## Files\n\n- `SKILL.md` - This documentation\n- `linear-transform.js` - Webhook payload parser and agent router\n- `linear-api.js` - Linear GraphQL API client (for posting comments)\n- `example-payload.json` - Sample Linear webhook payload for testing\n\n## References\n\n- [Clawdbot Webhook Docs](/automation/webhook)\n- [Linear Webhooks API](https://developers.linear.app/docs/graphql/webhooks)\n- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":2161,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1769691721565,"updatedAt":1779076559534},"latestVersion":{"version":"1.0.0","createdAt":1769691721565,"changelog":"Initial release of linear-webhook skill.\n\n- Enables dispatching tasks to Clawdbot agents through @mentions in Linear issue comments.\n- Webhook listens for Linear comment events and routes tasks to the correct agent (e.g., @mason for implementation, @eureka for strategy).\n- Includes detailed setup and configuration instructions for webhooks, agent routing, and security.\n- Supports customization for adding more agents and changing response behavior.\n- Provides troubleshooting and Linear API integration guidance.","license":null},"metadata":null,"owner":{"handle":"arnarsson","userId":"s1703vde870n8r5vvwnrs7xpg9884rg5","displayName":"Arnarsson","image":"https://avatars.githubusercontent.com/u/96142966?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779917646114}}