Integration
Linear Agent Bridge
By OpenClaw plugin that turns Linear into a multi-agent workspace β autonomous issue resolution, delegation, progress tracking, and more.
Install
npm install linear-agent-bridgeConfiguration Example
{
"openclaw": {
"extensions": ["./dist/index.js"]
}
}README
# linear-agent-bridge
An [OpenClaw](https://github.com/nicepkg/openclaw) plugin that turns Linear's Agent Sessions into fully autonomous AI agent runs. When someone @mentions or delegates an issue to your agent in Linear, this plugin receives the webhook, spins up an OpenClaw agent, and gives it a rich set of tools to manage issues, communicate progress, delegate work, and close tasks β all without leaving Linear.
## Table of Contents
- [How It Works](#how-it-works)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Linear App Setup](#linear-app-setup)
- [Plugin Configuration](#plugin-configuration)
- [Webhook Setup](#webhook-setup)
- [Use Cases](#use-cases)
- [Agent API Reference](#agent-api-reference)
- [Issue Management](#issue-management)
- [Communication (Activities)](#communication-activities)
- [Session Management](#session-management)
- [Delegation](#delegation)
- [Queries](#queries)
- [Architecture](#architecture)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [License](#license)
## How It Works
```
ββββββββββββ
β Linear β
β Workspaceβ
ββββββ¬ββββββ
β Webhook (AgentSession / Comment)
βΌ
ββββββββββββββββββ
β This Plugin β
β β
β 1. Verify HMAC β
β 2. Resolve β
β session ID β
β 3. Build β
β enriched β
β prompt β
β 4. Issue β
β per-session β
β API token β
βββββββββ¬βββββββββ
β callGateway({ method: "agent", ... })
βΌ
ββββββββββββββββββ
β OpenClaw Agent β
β β
β Reads issue, ββββββ POST /plugins/linear/api
β writes code, β (bearer token auth)
β posts updates ββββββΊ Linear GraphQL API
β to Linear β
ββββββββββββββββββ
```
1. A user @mentions the agent or delegates an issue in Linear
2. Linear sends a webhook to this plugin
3. The plugin verifies the HMAC signature, resolves the agent session, and builds an enriched prompt containing the issue context and a full API reference
4. An OpenClaw agent is launched with that prompt and a short-lived bearer token
5. During execution, the agent calls back to the plugin's API proxy to post thoughts, update plans, create sub-issues, delegate, query data, and post final responses
6. When the agent finishes, the token is revoked and the response is posted to Linear
## Features
- **Full Linear Agent Protocol** β implements `created`, `prompted`, `stop` signal, agent plans, activities (thought/action/elicitation/response/error), proactive sessions
- **Rich Agent API** β during execution the agent can manage issues, post activities, update session plans, delegate work, query issue/team details, and more
- **Session Deduplication** β prevents duplicate agent runs when Linear sends both AgentSession and Comment webhooks for the same event
- **Close Intent Detection** β recognizes natural-language close commands in English and Russian ("close this task", "Π·Π°ΠΊΡΠΎΠΉ Π·Π°Π΄Π°ΡΡ") and fast-paths them without a full agent run
- **Per-Session Security** β each agent run gets a unique cryptographic bearer token scoped to its session; revoked on completion
- **Issue Policies** β automatically moves issues to "started" state and delegates to the app user on session creation
- **Multi-Repo Routing** β maps Linear teams and projects to specific repository directories
- **Elicitation with Select** β the agent can present clickable option lists to users via the `select` signal
- **External URL Linking** β attaches external links (e.g. CI dashboard, PR) to the Linear session
- **Auto-Detection of Base URL** β works behind Tailscale or any reverse proxy; captures the public URL from the first webhook `Host` header
## Prerequisites
- **Node.js** >= 18
- A running **OpenClaw gateway** instance
- A **Linear workspace** with admin access (to install an OAuth application)
- A publicly reachable URL for webhooks (Tailscale, ngrok, cloud deploy, etc.)
## Installation
```bash
# From npm (when published)
npm install linear-agent-bridge
# Or clone and build from source
git clone https://github.com/tokezooo/linear-agent-bridge.git
cd linear-agent-bridge
npm install
npm run build
```
The plugin registers itself with OpenClaw via the `openclaw` field in `package.json`:
```json
{
"openclaw": {
"extensions": ["./dist/index.js"]
}
}
```
## Linear App Setup
### 1. Create a Linear Application
1. Go to **Linear Settings** > **API** > **Applications** > [Create new](https://linear.app/settings/api/applications/new)
2. Set a recognizable name (this is how users will see the agent in mentions and filters)
3. Enable **Webhooks**
4. Under webhook events, select **Agent session events**
5. Set the webhook URL to: `https://<your-host>/plugins/linear/linear`
### 2. OAuth Installation
Install the app into your workspace using the OAuth flow with `actor=app`:
```
https://linear.app/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT&response_type=code&scope=read,write,issues:create,comments:create,app:assignable,app:mentionable&actor=app
```
Key scopes:
| Scope | Purpose |
|-------|---------|
| `read`, `write` | Core issue/comment access |
| `issues:create` | Create issues and sub-issues |
| `comments:create` | Post comments |
| `app:assignable` | Allow delegation to the agent |
| `app:mentionable` | Allow @mentioning the agent |
### 3. Get the Webhook Signing Secret
In your Linear application settings, copy the **Webhook signing secret**. This is used for HMAC-SHA256 signature verification of incoming webhooks.
## Plugin Configuration
Configure the plugin in your OpenClaw config under the plugin's section. All options are defined in `openclaw.plugin.json`.
### Required
| Option | Type | Description |
|--------|------|-------------|
| `linearApiKey` | `string` | Linear OAuth token (from the OAuth flow above) |
| `linearWebhookSecret` | `string` | Webhook signing secret for HMAC verification |
### Recommended
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `devAgentId` | `string` | `"dev"` | OpenClaw agent ID to handle Linear issues |
| `defaultDir` | `string` | β | Default repository directory for agent work |
### Issue Policies
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `delegateOnCreate` | `boolean` | `true` | Auto-delegate issues to the app user when a session is created |
| `startOnCreate` | `boolean` | `true` | Move issues to "started" workflow state on session creation |
### Multi-Repo Routing
| Option | Type | Description |
|--------|------|-------------|
| `repoByTeam` | `object` | Map Linear team keys to repository directories. Example: `{ "ENG": "/home/code/backend", "WEB": "/home/code/frontend" }` |
| `repoByProject` | `object` | Map Linear project keys to repository directories. Takes precedence over `repoByTeam` |
### Agent API
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableAgentApi` | `boolean` | `true` | Enable the API proxy that agents call during execution |
| `apiBaseUrl` | `string` | auto-detected | Override the auto-detected base URL for agent API callbacks |
### External URLs
| Option | Type | Description |
|--------|------|-------------|
| `externalUrlBase` | `string` | URL template for session links. Supports `{session}` and `{issue}` placeholders. Example: `https://dash.example.com/sessions/{session}` |
| `externalUrlLabel` | `string` | Label for external links (default: `"OpenClaw session"`) |
### Notifications
| Option | Type | Description |
|--------|------|-------------|
| `notifyChannel` | `string` | Channel for delivery notifications (e.g. `"discord"`) |
| `notifyTo` | `string` | Target for notifications (e.g. `"channel:123456"`) |
| `notifyAccountId` | `string` | Account ID for notifications |
### Example Configuration
```json
{
"linearApiKey": "lin_oauth_...",
"linearWebhookSecret": "whsec_...",
"devAgentId": "dev",
"defaultDir": "/home/projects/main-repo",
"repoByTeam": {
"ENG": "/home/projects/backend",
"WEB": "/home/projects/frontend"
},
"delegateOnCreate": true,
"startOnCreate": true,
"enableAgentApi": true,
"externalUrlBase": "https://dash.example.com/sessions/{session}"
}
```
## Webhook Setup
The plugin registers a POST endpoint at `/plugins/linear/linear`.
### Security
- **HMAC-SHA256 Signature Verification** β every incoming webhook is verified against the `linearWebhookSecret` using the `linear-signature` header
- **Stale Webhook Rejection** β webhooks older than 60 seconds are rejected
- **Immediate 202 Response** β webhook processing happens asynchronously after responding to Linear
### What Gets Processed
| Event Type | Action | Result |
|------------|--------|--------|
| AgentSession `created` | New session | Full agent run with enriched prompt |
| AgentSession `prompted` | Follow-up message | Agent continues with new context |
| Comment (on agent thread) | Follow-up | Resolved to session, triggers `prompted` |
| Signal `stop` | Halt | Agent posts stop confirmation, no run |
| Close intent ("close task") | Fast-path | Issue closed directly, no agent run |
### What Gets Filtered
- `PermissionChange` and `OAuthApp` events (logged only)
- `AppUserNotification` events
- Self-authored comments (prevents feedback loops)
- System echo messages (e.g. "Starting work on...", "Agent run failed:")
- Empty prompts
- Duplicate events within the dedup window (5 seconds)
## Use Cases
### 1. Autonomous Issue Resolution
Delegate an issue to the agent in Linear. Th
... (truncated)
integration
Comments
Sign in to leave a comment