Linear

The Linear adapter treats issue comments as messages and issues as threads.

Installation

Terminal

pnpm add @chat-adapter/linear

Usage

The adapter auto-detects credentials from LINEAR_API_KEY (or LINEAR_CLIENT_ID/LINEAR_CLIENT_SECRET), LINEAR_WEBHOOK_SECRET, and LINEAR_BOT_USERNAME environment variables:

lib/bot.ts

import { Chat } from "chat";
import { createLinearAdapter } from "@chat-adapter/linear";

const bot = new Chat({
  userName: "my-bot",
  adapters: {
    linear: createLinearAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Linear!");
});

Authentication

Option A: Personal API key

Best for personal projects, testing, or single-workspace bots. Actions are attributed to you as an individual.

Go to Settings > Security & Access
Under Personal API keys, click Create key
Select Only select permissions and enable Create issues, Create comments
Choose team access
Click Create and set LINEAR_API_KEY

lib/bot.ts

createLinearAdapter({
  apiKey: process.env.LINEAR_API_KEY!,
});

Option B: OAuth application (recommended)

The bot gets its own identity in Linear. The adapter handles token management internally.

Go to Settings > API > Applications
Create an OAuth2 application with your bot's name and icon
Enable client credentials tokens in the app settings
Note the Client ID and Client Secret

lib/bot.ts

createLinearAdapter({
  clientId: process.env.LINEAR_CLIENT_ID!,
  clientSecret: process.env.LINEAR_CLIENT_SECRET!,
});

The adapter uses the client credentials grant to obtain tokens automatically. Tokens are valid for 30 days and auto-refresh when expired.

Making the bot @-mentionable (optional)

To make the bot appear in Linear's @ mention dropdown as an Agent:

In your OAuth app settings, enable Agent session events under webhooks
Have a workspace admin install the app with actor=app and the app:mentionable scope:

https://linear.app/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://your-domain.com/callback&
  response_type=code&
  scope=read,write,comments:create,app:mentionable&
  actor=app

See the Linear Agents docs for full details.

Webhook setup

Webhook management requires workspace admin access. If you don't see the API settings page, ask a workspace admin to create the webhook for you.

Go to Settings > API and click Create webhook
Fill in:
- Label: A descriptive name (e.g., "Chat Bot")
- URL: https://your-domain.com/api/webhooks/linear
Copy the Signing secret as LINEAR_WEBHOOK_SECRET
Under Data change events, select:
- Comments (required)
- Issues (recommended)
- Emoji reactions (optional)
Under Team selection, choose All public teams or a specific team
Click Create webhook

Thread model

Linear has two levels of comment threading:

Type	Description	Thread ID format
Issue-level	Top-level comments on an issue	`linear:{issueId}`
Comment thread	Replies nested under a specific comment	`linear:{issueId}:c:{commentId}`

When a user writes a comment, the bot replies within the same comment thread.

Reactions

SDK emoji	Linear emoji
`thumbs_up`	👍
`thumbs_down`	👎
`heart`	❤️
`fire`	🔥
`rocket`	🚀
`eyes`	👀
`sparkles`	✨
`wave`	👋

Configuration

All options are auto-detected from environment variables when not provided.

Option	Required	Description
`apiKey`	No*	Personal API key. Auto-detected from `LINEAR_API_KEY`
`clientId`	No*	OAuth app client ID. Auto-detected from `LINEAR_CLIENT_ID`
`clientSecret`	No*	OAuth app client secret. Auto-detected from `LINEAR_CLIENT_SECRET`
`accessToken`	No*	Pre-obtained OAuth access token. Auto-detected from `LINEAR_ACCESS_TOKEN`
`webhookSecret`	No**	Webhook signing secret. Auto-detected from `LINEAR_WEBHOOK_SECRET`
`userName`	No	Bot display name. Auto-detected from `LINEAR_BOT_USERNAME` (default: `"linear-bot"`)
`logger`	No	Logger instance (defaults to `ConsoleLogger("info")`)

*One of apiKey, clientId/clientSecret, or accessToken is required (via config or env vars).

**webhookSecret is required — either via config or LINEAR_WEBHOOK_SECRET env var.

Environment variables

.env.local

# API Key auth
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx

# OR OAuth app auth
LINEAR_CLIENT_ID=your-client-id
LINEAR_CLIENT_SECRET=your-client-secret

# Required
LINEAR_WEBHOOK_SECRET=your-webhook-secret

Features

Feature	Supported
Mentions	Yes
Reactions (add)	Yes
Cards	Markdown
Modals	No
Streaming	No
DMs	No
File uploads	No
Typing indicator	No
Message history	Yes

Limitations

No typing indicators — Linear doesn't support typing indicators
No streaming — Messages posted in full (editing supported for updates)
No DMs — Linear doesn't have direct messages
No modals — Linear doesn't support interactive modals
Action buttons — Rendered as text; use link buttons for clickable actions
Remove reaction — Requires reaction ID lookup (not directly supported)

Troubleshooting

"Invalid signature" error

Verify LINEAR_WEBHOOK_SECRET matches the secret from your webhook configuration
The webhook secret is shown only once at creation — regenerate if lost

Bot not responding to mentions

Verify webhook events are configured with Comments resource type
Check that the webhook URL is correct and accessible
Ensure the userName config matches how users mention the bot
Linear may auto-disable webhooks after repeated failures

"Webhook expired" error

Webhook timestamp is too old (> 5 minutes)
Usually indicates a delivery delay or clock skew
Check that your server time is synchronized

Linear

On this page