linear-agent-bridge

An 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.

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     │
              └────────────────┘

A user @mentions the agent or delegates an issue in Linear
Linear sends a webhook to this plugin
The plugin verifies the HMAC signature, resolves the agent session, and builds an enriched prompt containing the issue context and a full API reference
An OpenClaw agent is launched with that prompt and a short-lived bearer token
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
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

# 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:

{
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Linear App Setup

1. Create a Linear Application

Go to Linear Settings > API > Applications > Create new
Set a recognizable name (this is how users will see the agent in mentions and filters)
Enable Webhooks
Under webhook events, select Agent session events
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. Token Exchange (low human-in-the-loop mode)

After the user authorizes your app, Linear redirects with ?code=.... This plugin can accept the code, exchange it, and persist tokens automatically:

GET /plugins/linear/oauth/callback?code=... (browser redirect target)
POST /plugins/linear/oauth/exchange with JSON { "code": "..." }

The token set is stored in linearTokenStorePath (default ~/.openclaw/workspace/.pi/linear-oauth.json) with restrictive file permissions, and refresh is attempted automatically when the access token expires.

4. 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
`linearWebhookSecret`	`string`	Webhook signing secret for HMAC verification

Authentication requires one of these modes:

Static token mode: set linearApiKey
OAuth automation mode: set linearOauthClientId, linearOauthClientSecret, linearOauthRedirectUri

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
`linearTokenStorePath`	`string`	`~/.openclaw/workspace/.pi/linear-oauth.json`	Workspace-local OAuth token store path (written with `0600`)
`apiCorsOrigins`	`string[]`	—	Allowed origins for CORS on `/plugins/linear/api`. Use `["*"]` to allow any origin
`apiCorsAllowCredentials`	`boolean`	`false`	Adds `Access-Control-Allow-Credentials: true` when origin is explicitly allowed

Addressing Controls

Option	Type	Default	Description
`strictAddressing`	`boolean`	`false`	Process only explicitly addressed events (mentions, delegation, thread replies)
`mentionHandle`	`string`	—	App mention handle used in strict mode (example: `personal-openclaw`)

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

{
  "linearWebhookSecret": "whsec_...",
  "linearOauthClientId": "...",
  "linearOauthClientSecret": "...",
  "linearOauthRedirectUri": "https://your-host/plugins/linear/oauth/callback",
  "linearTokenStorePath": "/home/ubuntu/.openclaw/workspace/.pi/linear-oauth.json",
  "devAgentId": "dev",
  "defaultDir": "/home/projects/main-repo",
  "repoByTeam": {
    "ENG": "/home/projects/backend",
    "WEB": "/home/projects/frontend"
  },
  "delegateOnCreate": true,
  "startOnCreate": true,
  "strictAddressing": true,
  "mentionHandle": "personal-openclaw",
  "enableAgentApi": true,
  "apiCorsOrigins": ["https://linear.app", "https://linear.com"],
  "apiCorsAllowCredentials": false,
  "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. The agent receives the full issue context (title, description, labels, comments), writes code, creates sub-issues for subtasks, posts progress updates, and closes the issue when done.

2. Interactive Code Review

@mention the agent in a comment asking for review. The agent reads the issue context, examines the linked code, and posts structured feedback as a response activity.

3. Multi-Agent Delegation

The agent can delegate sub-tasks to other agents or reassign issues to human team members:

{ "action": "delegate/assign", "issueId": "...", "delegateId": "other-agent-id" }

4. Issue Triage and Breakdown

Ask the agent to break down a large issue. It creates sub-issues with appropriate priorities and links them to the parent:

{ "action": "issue/create-sub-issue", "title": "Implement auth middleware", "priority": 1 }

5. Progress Tracking

The agent shows real-time progress via session plans — structured checklists visible in the Linear UI:

{
  "action": "session/plan",
  "plan": [
    { "content": "Analyze issue requirements", "status": "completed" },
    { "content": "Implement solution", "status": "inProgress" },
    { "content": "Write tests", "status": "pending" },
    { "content": "Post summary", "status": "pending" }
  ]
}

6. User Elicitation

The agent can ask the user to choose between options using the select signal:

{
  "action": "activity/elicitation",
  "body": "Which approach should I take?",
  "signal": "select",
  "signalMeta": {
    "options": [
      { "value": "Refactor the existing module" },
      { "value": "Write a new implementation from scratch" }
    ]
  }
}

7. Proactive Sessions

The agent can create new sessions on other issues or comments without being explicitly delegated:

{ "action": "session/create-on-issue", "issueId": "issue-uuid" }

Agent API Reference

During execution, the agent makes HTTP POST requests to a single endpoint. All requests use bearer token authentication and a JSON body with an action field.

Endpoint: POST <apiBaseUrl> Auth: Authorization: Bearer <per-session-token> Content-Type: application/json

Every request body must include an action field.

Issue Management

`issue/create` — Create a New Issue

Field	Type	Required	Description
`teamId`	`string`	No (defaults to current)	Team to create issue in
`title`	`string`	Yes	Issue title
`description`	`string`	No	Issue description (Markdown)
`priority`	`number`	No	Priority 0-4 (0 = no priority, 1 = urgent, 4 = low)
`labelIds`	`string[]`	No	Label IDs to attach
`assigneeId`	`string`	No	Assignee user ID
`parentId`	`string`	No	Parent issue ID (creates sub-issue)
`stateId`	`string`	No	Initial workflow state

`issue/update` — Update Issue Fields

Field	Type	Required	Description
`issueId`	`string`	No (defaults to current)	Issue to update
`title`	`string`	No	New title
`description`	`string`	No	New description
`stateId`	`string`	No	New workflow state
`priority`	`number`	No	New priority
`labelIds`	`string[]`	No	Replace labels
`assigneeId`	`string`	No	New assignee
`delegateId`	`string`	No	New delegate

`issue/close` — Close an Issue

Field	Type	Required	Description
`issueId`	`string`	No (defaults to current)	Issue to close

Resolves the team's "completed" workflow state and transitions the issue. Returns alreadyClosed: true if the issue is already completed or canceled.

`issue/create-sub-issue` — Create a Child Issue

Field	Type	Required	Description
`title`	`string`	Yes	Sub-issue title
`parentId`	`string`	No (defaults to current)	Parent issue
`description`	`string`	No	Description
`priority`	`number`	No	Priority 0-4
`labelIds`	`string[]`	No	Labels
`assigneeId`	`string`	No	Assignee

`issue/link` — Link Two Issues

Field	Type	Required	Description
`issueId`	`string`	No (defaults to current)	Source issue
`relatedIssueId`	`string`	Yes	Target issue
`type`	`string`	Yes	One of: `blocks`, `blocked_by`, `related`, `duplicate`

Communication (Activities)

Activities are how the agent communicates with users in the Linear session UI.

`activity/thought` — Share Reasoning

Field	Type	Required	Description
`body`	`string`	Yes	Markdown text
`ephemeral`	`boolean`	No	If `true`, shown temporarily and replaced by next activity

`activity/action` — Show a Tool Call

Field	Type	Required	Description
`activityAction`	`string`	Yes	Action verb (e.g. "Searching", "Building")
`parameter`	`string`	No	Subject of the action
`result`	`string`	No	Result (Markdown)

`activity/elicitation` — Ask the User a Question

Field	Type	Required	Description
`body`	`string`	Yes	Question text
`signal`	`string`	No	Set to `"select"` to show option buttons
`signalMeta`	`object`	No	`{ options: [{ value: "..." }] }` — list of choices

`activity/response` — Post Final Response

Field	Type	Required	Description
`body`	`string`	Yes	Final response (Markdown)

Marks the session as having a posted response. The handler will skip auto-posting the agent's text output.

`activity/error` — Report an Error

Field	Type	Required	Description
`body`	`string`	Yes	Error description

Session Management

`session/plan` — Update Progress Checklist

Field	Type	Required	Description
`plan`	`array`	Yes	Array of plan steps

Each step: { content: "Step description", status: "pending" | "inProgress" | "completed" | "canceled" }

Note: Replaces the entire plan each time. Always include all steps.

`session/create-on-issue` — Create Session on Another Issue

Field	Type	Required	Description
`issueId`	`string`	Yes	Issue to create session on

`session/create-on-comment` — Create Session on a Comment

Field	Type	Required	Description
`commentId`	`string`	Yes	Comment to create session on

`session/external-url` — Set External URL

Field	Type	Required	Description
`url`	`string`	Yes	URL to attach
`label`	`string`	No	Link label (default: `"Link"`)

Delegation

`delegate/assign` — Delegate to Agent or User

Field	Type	Required	Description
`issueId`	`string`	No (defaults to current)	Issue to delegate
`delegateId`	`string`	Yes	Target agent or user ID

`delegate/reassign` — Change Assignee

Field	Type	Required	Description
`issueId`	`string`	No (defaults to current)	Issue to reassign
`assigneeId`	`string`	Yes	New assignee ID

Queries

`query/issue` — Get Full Issue Details

Field	Type	Required	Description
`issueId`	`string`	No (defaults to current)	Issue ID

Returns: labels, state, assignee, delegate, parent, children, relations, recent comments.

`query/team` — Get Team Info

Field	Type	Required	Description
`teamId`	`string`	No (defaults to current)	Team ID

Returns: workflow states, labels, members.

`query/repo-suggestions` — Get AI-Ranked Repository Suggestions

Field	Type	Required	Description
`issueId`	`string`	No (defaults to current)	Issue for context
`candidateRepositories`	`array`	Yes	`[{ hostname, repositoryFullName }]`

Returns ranked suggestions with confidence scores.

`query/viewer` — Get Current App Identity

No parameters. Returns the authenticated app's user ID.

Architecture

index.ts                          ← Entry point: registers HTTP routes
├── src/
│   ├── types.ts                  ← Shared TypeScript interfaces
│   ├── config.ts                 ← Plugin config normalization
│   ├── util.ts                   ← HTTP/JSON helpers
│   ├── linear-client.ts          ← Single gateway for all Linear GraphQL calls
│   ├── graphql/
│   │   ├── queries.ts            ← GraphQL query strings
│   │   └── mutations.ts          ← GraphQL mutation strings
│   ├── webhook/
│   │   ├── handler.ts            ← Main webhook handler + agent orchestration
│   │   ├── validation.ts         ← HMAC-SHA256 signature verification
│   │   ├── session-resolver.ts   ← Session ID lookup (direct → cache → GraphQL)
│   │   ├── message-builder.ts    ← Agent prompt construction
│   │   ├── response-parser.ts    ← Parse agent output into response text
│   │   ├── issue-policy.ts       ← Auto-start and auto-delegate policies
│   │   ├── close-intent.ts       ← Natural language close detection
│   │   └── skip-filter.ts        ← System echo and self-comment filtering
│   ├── api/
│   │   ├── router.ts             ← API proxy router (bearer token auth)
│   │   ├── base-url.ts           ← Auto-detect public URL from Host header
│   │   ├── issue-ops.ts          ← Issue CRUD operations
│   │   ├── activity-ops.ts       ← Agent activity posting
│   │   ├── session-ops.ts        ← Session management (plans, proactive creation)
│   │   ├── delegation-ops.ts     ← Issue delegation and reassignment
│   │   └── query-ops.ts          ← Read-only queries (issue, team, viewer)
│   └── agent/
│       ├── session-token.ts      ← Per-run bearer token lifecycle
│       ├── context-builder.ts    ← Enriched prompt with API documentation
│       ├── response-tracker.ts   ← Tracks whether agent already posted a response
│       └── plan-manager.ts       ← In-memory plan state per session

Key Design Patterns

Pattern	Description
Single Linear Gateway	All GraphQL communication goes through `callLinear()` which handles auth, errors, and logging
Per-Session Tokens	Each agent run gets a unique `crypto.randomBytes(32)` bearer token, revoked on completion
Response Deduplication	If the agent posts a response via the API, the handler skips auto-posting the text output
Cascading Session Resolution	Direct field → in-memory cache → GraphQL query with retry (120ms/350ms/800ms backoff)
Side-Effect Registration	API handlers register themselves via `registerApiHandler()` and are imported in `index.ts`
Dedup Window	Prevents double agent runs when Linear sends both AgentSession + Comment webhooks (5s window)

Development

Build

npm run build    # Runs tsc, outputs to dist/

Project Structure

TypeScript with strict: true, targeting ES2022
ESM ("type": "module" in package.json)
Node16 module resolution
Zero runtime dependencies (only @types/node and typescript as dev deps)

Adding a New API Operation

Create a file in src/api/ (e.g. my-ops.ts)
Import and use registerApiHandler:

import { registerApiHandler } from "./router.js";
import { sendJson } from "../util.js";

registerApiHandler("/my/action", async ({ api, cfg, context, body, res }) => {
  // context.sessionId, context.issueId, context.teamId are available
  // body contains the parsed JSON request
  sendJson(res, 200, { ok: true });
});

Add a side-effect import in index.ts:

import "./src/api/my-ops.js";

The handler is now available as { "action": "my/action" } through the API proxy.

Troubleshooting

Webhook not reaching the plugin

Verify the URL in Linear application settings matches https://<host>/plugins/linear/linear
Ensure your host is publicly reachable (check with curl)
Check that "Agent session events" is enabled in the Linear app webhook settings

401 Unauthorized on webhook

Verify linearWebhookSecret matches the signing secret from Linear app settings
Check that the webhook is not stale (>60 seconds old) — clock sync issues can cause this

Agent doesn't respond in Linear

Check that linearApiKey is a valid OAuth token with the required scopes
Verify the agent ID in devAgentId matches a configured OpenClaw agent
Check OpenClaw gateway logs for errors

Agent API calls fail

If apiBaseUrl is not set, the URL is auto-detected from the first webhook's Host header. Ensure your reverse proxy forwards the correct Host
For Tailscale setups, the Host header with .ts.net domain is used automatically
Set apiBaseUrl explicitly to bypass auto-detection

Self-comment loop

The plugin automatically filters out comments authored by the app itself using the viewer query
If you see loops, verify that the linearApiKey belongs to the same OAuth application that sends the webhooks

License

MIT © tokezooo

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
index.ts		index.ts
openclaw.plugin.json		openclaw.plugin.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Option	Type	Default	Description
`devAgentId`	`string`	`"dev"`	OpenClaw agent ID to handle Linear issues
`defaultDir`	`string`	—	Default repository directory for agent work

Folders and files

Latest commit

History

Repository files navigation

linear-agent-bridge

Table of Contents

How It Works

Features

Prerequisites

Installation

Linear App Setup

1. Create a Linear Application

2. OAuth Installation

3. Token Exchange (low human-in-the-loop mode)

4. Get the Webhook Signing Secret

Plugin Configuration

Required

Recommended

Issue Policies

Multi-Repo Routing

Agent API

Addressing Controls

External URLs

Notifications

Example Configuration

Webhook Setup

Security

What Gets Processed

What Gets Filtered

Use Cases

1. Autonomous Issue Resolution

2. Interactive Code Review

3. Multi-Agent Delegation

4. Issue Triage and Breakdown

5. Progress Tracking

6. User Elicitation

7. Proactive Sessions

Agent API Reference

Issue Management

issue/create — Create a New Issue

issue/update — Update Issue Fields

issue/close — Close an Issue

issue/create-sub-issue — Create a Child Issue

issue/link — Link Two Issues

Communication (Activities)

activity/thought — Share Reasoning

activity/action — Show a Tool Call

activity/elicitation — Ask the User a Question

activity/response — Post Final Response

activity/error — Report an Error

Session Management

session/plan — Update Progress Checklist

session/create-on-issue — Create Session on Another Issue

session/create-on-comment — Create Session on a Comment

session/external-url — Set External URL

Delegation

delegate/assign — Delegate to Agent or User

delegate/reassign — Change Assignee

Queries

query/issue — Get Full Issue Details

query/team — Get Team Info

query/repo-suggestions — Get AI-Ranked Repository Suggestions

query/viewer — Get Current App Identity

Architecture

Key Design Patterns

Development

Build

Project Structure

Adding a New API Operation

Troubleshooting

Webhook not reaching the plugin

401 Unauthorized on webhook

Agent doesn't respond in Linear

Agent API calls fail

Self-comment loop

License

About

Resources

License

Uh oh!

`issue/create` — Create a New Issue

`issue/update` — Update Issue Fields

`issue/close` — Close an Issue

`issue/create-sub-issue` — Create a Child Issue

`issue/link` — Link Two Issues

`activity/thought` — Share Reasoning

`activity/action` — Show a Tool Call

`activity/elicitation` — Ask the User a Question

`activity/response` — Post Final Response

`activity/error` — Report an Error

`session/plan` — Update Progress Checklist

`session/create-on-issue` — Create Session on Another Issue

`session/create-on-comment` — Create Session on a Comment

`session/external-url` — Set External URL

`delegate/assign` — Delegate to Agent or User

`delegate/reassign` — Change Assignee

`query/issue` — Get Full Issue Details

`query/team` — Get Team Info

`query/repo-suggestions` — Get AI-Ranked Repository Suggestions

`query/viewer` — Get Current App Identity

Packages