Linear Webhook

Comment @mason or @eureka in Linear issues to dispatch tasks to agents. Webhook receives Linear comments and routes to correct agent.

Security Scan

The skill's stated purpose (routing Linear @mentions to agents) is plausible, but the package and runtime instructions ask for local secret files, hard-coded paths, and other credentials that are not declared in the registry metadata—this mismatch warrants caution before installing.

Purpose & Capability

Name/description match the code: it parses Linear comment webhooks and routes to agents. However, the registry lists no required environment variables or credentials while SKILL.md and the code require a hook token, a Linear API key, and optionally agent OAuth tokens. The code also references hard-coded paths (e.g., /home/sven/clawd-mason/..., ~/.linear_api_key) which are environment-specific and not appropriate to be undeclared.

Instruction Scope

Runtime instructions and the transform build a task that explicitly tells operators/agents to read local secret files (cat ~/.linear_api_key) and run node -e code that requires the skill module. The code itself reads ~/.linear_api_key and ~/.config/clawdbot/linear-agent-tokens.json, and post-response.js spawns shell commands (clawdbot sessions history). These behaviors extend beyond simple webhook parsing into reading local secrets and running shell commands.

Install Mechanism

There is no install spec (instruction-only with bundled code), so the skill does not download remote artifacts during install. That lowers install-time risk. It does assume external tools (cloudflared/tailscale, clawdbot CLI, Node.js) are present but does not install them itself.

Credentials

Registry metadata declares no required env vars, but SKILL.md and code require/encourage: CLAWDBOT_HOOK_TOKEN, LINEAR_API_KEY or CLAWDBOT_LINEAR_API_KEY, and possibly agent OAuth tokens stored under ~/.config. The code prefers reading secrets from disk (~/.linear_api_key), which increases risk and is disproportionate to a simple webhook transform. The skill also logs and prints task content (may include issue contents) and therefore has access to potentially sensitive project data.

Persistence & Privilege

always is false (normal) and the skill does not request to alter other skills or system-wide configs. However, bundled scripts reference absolute paths and local token files, which imply assumptions about filesystem layout and persistent storage of credentials; run-time file reads grant it access to secrets in the user's home directory.

What to consider before installing

This skill generally does what it says (route @mentions to agents), but there are a few red flags you should act on before installing: - Manifest mismatch: The registry lists no required credentials, but SKILL.md and the code require a webhook token and a Linear API key (and may read agent OAuth tokens). Treat this as a sign the package metadata is incomplete or careless. - Local secret files & hard-coded paths: The code reads ~/.linear_api_key and ~/.config/clawdbot/linear-agent-tokens.json and references /home/sven/… paths. Before use, remove or fix hard-coded paths and prefer environment variables over reading plain files. If you keep a file-based key, ensure its filesystem permissions are strict (600) and it is stored in a secure location. - Shell execution: post-response.js executes the Clawdbot CLI and the code shows examples that run node -e with require() to call postLinearComment. Review those commands and avoid running arbitrary node -e snippets from untrusted sources. - Least privilege: Provide the Linear API token with the minimal scopes needed (write only where necessary) and consider using a dedicated Linear bot account instead of a personal API key. Rotate tokens and revoke them if you stop using the skill. - Network exposure: The instructions recommend Cloudflare Tunnel / Tailscale Funnel. If you expose a webhook, ensure the webhook endpoint requires the CLAWDBOT_HOOK_TOKEN header and restrict incoming sources if possible. - Code review: Because the skill was published from an unknown source, review the included JS scripts for any additional hidden network endpoints or data exfiltration paths (the current files do not point to suspicious external endpoints, but they do read and use local secrets). If you cannot review the code, run it in an isolated environment/container and limit its network and filesystem access. - Suggested changes before production use: - Update the skill metadata to declare required env vars (CLAWDBOT_HOOK_TOKEN, LINEAR_API_KEY) so the registry is honest about secrets needed. - Replace file-based secret reads with well-documented environment variable usage and explicit config paths. - Remove hard-coded absolute paths; make module import paths relative or configurable. - Add comment/response posting to use a dedicated app-level token and confirm how attribution is handled. If you accept those mitigations (or can run the skill in a sandboxed environment), the skill appears usable. Without those changes, treat it cautiously and avoid placing production secrets where the code expects them.

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