openclaw-linear-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stumct
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# OpenClaw Linear Plugin
+
+Receive [Linear](https://linear.app) Agent Session webhooks and run [OpenClaw](https://github.com/openclaw/openclaw) agents on issues.
+
+When a Linear issue is delegated to your agent app, this plugin:
+1. Receives the webhook
+2. Starts an OpenClaw agent session
+3. Posts the agent's response back to Linear
+
+## Installation
+
+```bash
+npm install openclaw-linear-plugin
+```
+
+## Prerequisites
+
+### 1. Create a Linear Agent Application
+
+1. Go to [Linear Settings → API → Applications](https://linear.app/settings/api/applications/new)
+2. Create a new application with:
+   - Name: Your agent name (e.g., "DevBot")
+   - Webhook URL: `https://your-gateway/plugins/linear/linear`
+   - Enable **Agent session events** in webhook categories
+
+### 2. Install the App via OAuth
+
+Complete the OAuth flow with these parameters:
+```
+https://linear.app/oauth/authorize?
+  client_id=YOUR_CLIENT_ID&
+  response_type=code&
+  scope=read,write,app:assignable,app:mentionable&
+  actor=app&
+  redirect_uri=YOUR_REDIRECT_URI
+```
+
+The `actor=app` parameter is required for agent functionality.
+
+### 3. Expose Your Gateway
+
+The webhook URL must be publicly accessible. If using [Tailscale](https://tailscale.com), enable Funnel:
+
+```bash
+tailscale funnel 18789  # Replace with your gateway port
+```
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "linear": {
+        "enabled": true,
+        "config": {
+          "devAgentId": "dev",
+          "linearWebhookSecret": "lin_wh_...",
+          "linearApiKey": "lin_oauth_...",
+          "defaultDir": "/path/to/repo",
+          "delegateOnCreate": true,
+          "startOnCreate": true
+        }
+      }
+    }
+  }
+}
+```
+
+### Config Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `devAgentId` | string | Agent ID to handle issues (default: `"dev"`) |
+| `linearWebhookSecret` | string | Webhook signing secret from Linear |
+| `linearApiKey` | string | OAuth token from Linear app installation |
+| `defaultDir` | string | Default repository directory |
+| `repoByTeam` | object | Map team keys to repo directories |
+| `repoByProject` | object | Map project keys to repo directories |
+| `delegateOnCreate` | boolean | Auto-delegate issues to app (default: `true`) |
+| `startOnCreate` | boolean | Move issues to "started" state (default: `true`) |
+| `notifyChannel` | string | Optional: Channel for notifications (e.g., `"discord"`) |
+| `notifyTo` | string | Optional: Notification target (e.g., `"channel:123456"`) |
+| `externalUrlBase` | string | Optional: External session URL template |
+| `externalUrlLabel` | string | Optional: Label for external URL link |
+
+### External URL Template
+
+Use placeholders for dynamic URLs:
+```json
+{
+  "externalUrlBase": "https://your-app.com/sessions/{session}",
+  "externalUrlLabel": "View Session"
+}
+```
+
+Supports `{session}` and `{issue}` placeholders.
+
+## How It Works
+
+1. **Webhook Reception**: Linear sends an AgentSessionEvent when an issue is delegated to your app
+2. **Initial Response**: Plugin posts a "thinking" activity within 5 seconds
+3. **Agent Execution**: OpenClaw agent runs with the issue context
+4. **Response Posting**: Agent's reply is posted back to Linear as a response activity
+
+### Webhook Endpoint
+
+```
+POST /plugins/linear/linear
+```
+
+The plugin verifies the `Linear-Signature` header when `linearWebhookSecret` is configured.
+
+## Troubleshooting
+
+### "Did not respond" in Linear
+
+- Check that your webhook URL is publicly accessible
+- Verify `linearApiKey` has correct OAuth scopes
+- Check OpenClaw logs for errors
+
+### Webhook signature failures
+
+- Ensure `linearWebhookSecret` matches Linear's signing secret
+- Check for clock skew (webhooks older than 60s are rejected)
+
+### Agent not running
+
+- Verify `devAgentId` matches an agent in your OpenClaw config
+- Check that the agent has necessary tool permissions
+
+## Example Webhook Payload
+
+```json
+{
+  "action": "created",
+  "agentSession": {
+    "id": "session_abc123",
+    "issue": {
+      "id": "issue_xyz789",
+      "identifier": "ENG-123",
+      "title": "Fix login bug",
+      "url": "https://linear.app/team/issue/ENG-123"
+    }
+  },
+  "promptContext": "<issue>...</issue>",
+  "guidance": "Follow coding standards"
+}
+```
+
+## License
+
+MIT © stumct

package/openclaw.plugin.json

@@ -0,0 +1,79 @@
+{
+  "id": "linear",
+  "name": "Linear",
+  "description": "Linear agent webhook bridge for OpenClaw dev runs",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "devAgentId": {
+        "type": "string",
+        "description": "Agent ID to handle Linear issues (default: 'dev')"
+      },
+      "linearWebhookSecret": {
+        "type": "string",
+        "description": "Linear webhook signing secret for signature verification"
+      },
+      "linearApiKey": {
+        "type": "string",
+        "description": "Linear OAuth token for posting activities and updating issues"
+      },
+      "notifyChannel": {
+        "type": "string",
+        "description": "Optional channel to deliver agent responses (e.g., 'discord')"
+      },
+      "notifyTo": {
+        "type": "string",
+        "description": "Optional target for notifications (e.g., 'channel:123456')"
+      },
+      "notifyAccountId": {
+        "type": "string",
+        "description": "Optional account ID for notifications"
+      },
+      "repoByTeam": {
+        "type": "object",
+        "additionalProperties": { "type": "string" },
+        "description": "Map Linear team keys to repository directories"
+      },
+      "repoByProject": {
+        "type": "object",
+        "additionalProperties": { "type": "string" },
+        "description": "Map Linear project keys to repository directories"
+      },
+      "defaultDir": {
+        "type": "string",
+        "description": "Default repository directory when no team/project mapping matches"
+      },
+      "delegateOnCreate": {
+        "type": "boolean",
+        "description": "Auto-delegate issues to the app user on session create (default: true)"
+      },
+      "startOnCreate": {
+        "type": "boolean",
+        "description": "Move issues to 'started' state on session create (default: true)"
+      },
+      "externalUrlBase": {
+        "type": "string",
+        "description": "Base URL for external session links (supports {session} and {issue} placeholders)"
+      },
+      "externalUrlLabel": {
+        "type": "string",
+        "description": "Label for external session links (default: 'OpenClaw session')"
+      }
+    }
+  },
+  "uiHints": {
+    "linearWebhookSecret": { "label": "Webhook secret", "sensitive": true },
+    "linearApiKey": { "label": "API key / OAuth token", "sensitive": true },
+    "delegateOnCreate": { "label": "Auto delegate" },
+    "startOnCreate": { "label": "Move to started" },
+    "externalUrlBase": {
+      "label": "External session URL",
+      "placeholder": "https://your-gateway/sessions/{session}"
+    },
+    "externalUrlLabel": {
+      "label": "External URL label",
+      "placeholder": "OpenClaw session"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "openclaw-linear-plugin",
+  "version": "0.1.0",
+  "description": "Linear agent webhook integration for OpenClaw",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "openclaw",
+    "linear",
+    "agent",
+    "webhook",
+    "plugin"
+  ],
+  "author": "stumct",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stumct/openclaw-linear-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/stumct/openclaw-linear-plugin/issues"
+  },
+  "homepage": "https://github.com/stumct/openclaw-linear-plugin#readme",
+  "peerDependencies": {
+    "openclaw": ">=0.1.0"
+  },
+  "devDependencies": {
+    "openclaw": "^0.1.0",
+    "typescript": "^5.0.0"
+  }
+}