vercel__chat/packages/adapter-linear

@chat-adapter/linear

Linear adapter for Chat SDK. Respond to @mentions in issue comment threads.

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

Installation

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:

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.

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

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.

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

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:

1. In your OAuth app settings, enable Agent session events under webhooks
2. 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

Note: 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.

1. Go to Settings > API and click Create webhook
2. Fill in:
   • Label: A descriptive name (e.g., "Chat Bot")
   • URL: https://your-domain.com/api/webhooks/linear
3. Copy the Signing secret as LINEAR_WEBHOOK_SECRET
4. Under Data change events, select:
   • Comments (required)
   • Issues (recommended)
   • Emoji reactions (optional)
5. Under Team selection, choose All public teams or a specific team
6. 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_up
thumbs_down	thumbs_down
heart	heart
fire	fire
rocket	rocket
eyes	eyes
sparkles	sparkles
wave	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

# 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

Messaging

Feature	Supported
Post message	Yes
Edit message	Yes
Delete message	Yes
File uploads	No
Streaming	No

Rich content

Feature	Supported
Card format	Markdown
Buttons	No
Link buttons	No
Select menus	No
Tables	GFM
Fields	Yes
Images in cards	No
Modals	No

Conversations

Feature	Supported
Slash commands	No
Mentions	Yes
Add reactions	Yes
Remove reactions	Partial
Typing indicator	No
DMs	No
Ephemeral messages	No

Message history

Feature	Supported
Fetch messages	Yes
Fetch single message	No
Fetch thread info	Yes
Fetch channel messages	No
List threads	No
Fetch channel info	No
Post channel message	No

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

License

MIT