To scaffold a new Linear bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter linear memory
Visit the adapters directory to see other available official and vendor-official adapters.
Quick start
For managed credentials and webhook verification, see Vercel Connect.
The adapter auto-detects credentials from LINEAR_API_KEY, LINEAR_ACCESS_TOKEN, LINEAR_CLIENT_CREDENTIALS_CLIENT_ID/LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET, or LINEAR_CLIENT_ID/LINEAR_CLIENT_SECRET, plus LINEAR_WEBHOOK_SECRET and LINEAR_BOT_USERNAME:
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!");});
The adapter defaults to mode: "comments" and handles Comment webhooks. For Vercel Connect and Linear app-actor installations, we recommend explicitly setting mode: "agent-sessions" to handle AgentSessionEvent webhooks, including mentions and replies within a session.
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
accessToken
No*
OAuth access token. Accepts a string, or (Vercel Connect) a () => string | Promise<string> resolver invoked per API call. Auto-detected from LINEAR_ACCESS_TOKEN
clientId
No*
Multi-tenant OAuth app client ID. Auto-detected from LINEAR_CLIENT_ID
clientSecret
No*
Multi-tenant OAuth app client secret. Auto-detected from LINEAR_CLIENT_SECRET
encryptionKey
No
AES-256-GCM key for encrypting stored OAuth tokens. Auto-detected from LINEAR_ENCRYPTION_KEY
clientCredentials
No*
Single-tenant client credentials config
clientCredentials.scopes
No
Scopes for client credentials auth. Defaults to ["read", "write", "comments:create", "issues:create"]
mode
No
Inbound webhook handling mode. Defaults to "comments". Set "agent-sessions" for the recommended Connect setup
webhookSecret
No**
Webhook signing secret. Auto-detected from LINEAR_WEBHOOK_SECRET
webhookVerifier
No**
Custom verifier (request, body) => unknown | Promise<unknown> used in place of webhookSecret. Takes precedence over webhookSecret/LINEAR_WEBHOOK_SECRET. Required in Connect mode
userName
No
Bot display name. Auto-detected from LINEAR_BOT_USERNAME (default: "linear-bot")
apiUrl
No
Override the Linear GraphQL API base URL. Auto-detected from LINEAR_API_URL
logger
No
Logger instance (defaults to ConsoleLogger("info"))
*One of apiKey, accessToken (string or Vercel Connect resolver), top-level clientId/clientSecret, or clientCredentials is required (via config or env vars).
**Either webhookSecret (via config or LINEAR_WEBHOOK_SECRET) or a webhookVerifier is required. When webhookVerifier is set it takes precedence and the secret is ignored.
Authentication
Option A — Vercel Connect
Use Vercel Connect to source the Linear access token at runtime instead of storing a long-lived token or OAuth secret. Pass accessToken as a resolver and verify inbound webhooks with webhookVerifier (a Vercel OIDC token from Connect trigger forwarding) instead of a webhook secret.
The simplest path is the connectLinearAdapter() helper from @vercel/connect/chat:
import { createLinearAdapter } from "@chat-adapter/linear";import { connectLinearAdapter } from "@vercel/connect/chat";createLinearAdapter({ ...connectLinearAdapter("linear/acme-linear"), mode: "agent-sessions",});
We recommend agent sessions for Vercel Connect bots. Enable Agent session events on the Linear app and use an app-actor installation. Omitting mode keeps the "comments" default; existing bots do not need to change their configuration. Changing the adapter mode does not change the app's webhook subscriptions or permissions.
accessToken accepts a string or () => string | Promise<string> resolver invoked per API call, so it composes with Connect's short-lived tokens. When webhookVerifier is set it takes precedence over webhookSecret and LINEAR_WEBHOOK_SECRET.
Freshness: OIDC verification replaces Linear's signature + timestamp check, so request freshness relies on the short-lived OIDC token's expiry rather than the >5 min timestamp rejection, and there is no built-in delivery de-duplication. Keep your webhook handlers idempotent (Linear can also deliver events out of order).
Option B — Personal API key
Best for personal projects, testing, or single-workspace bots. Actions are attributed to you as an individual.
Use top-level clientId / clientSecret for Slack-style multi-tenant installs. Each Linear workspace installation is stored separately, webhook requests resolve the correct workspace token by organizationId, and withInstallation() lets you target a specific organization outside webhook handling.
await adapter.withInstallation("org-id", async () => { await adapter.postMessage("linear:issue-id", "Hello from a background job");});
Option E — Single-tenant client credentials
If you want app identity without multi-tenant installs, use the explicit clientCredentials config. The adapter fetches and refreshes the token automatically.
For multi-tenant OAuth installs, pass a base64-encoded 32-byte key as encryptionKey (or set LINEAR_ENCRYPTION_KEY) to encrypt stored access and refresh tokens at rest using AES-256-GCM:
openssl rand -base64 32
When encryptionKey is set, setInstallation() encrypts tokens before writing them to the configured state adapter and getInstallation() decrypts them transparently. Existing plaintext records continue to work, so you can roll the key in without flushing installs. Without an encryptionKey, tokens are stored in plaintext (the previous default).
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:
API key, access token, and single-tenant client-credentials modes return the same client anywhere. Multi-tenant OAuth mode requires webhook handler context to resolve the per-org token — calling .linearClient outside a handler throws.
The previous .client getter still works as a deprecated alias for .linearClient.
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.
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 for mode: "comments")
Agent session events (required for mode: "agent-sessions")
Issues (recommended)
Emoji reactions (optional)
Under Team selection, choose All public teams or a specific team
Click Create webhook
Thread model
Linear has four thread variants:
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}
Agent session on issue
App-actor session attached to an issue
linear:{issueId}:s:{agentSessionId}
Agent session on comment thread
App-actor session attached to a comment thread
linear:{issueId}:c:{commentId}:s:{agentSessionId}
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
Environment variables
# API Key authLINEAR_API_KEY=lin_api_xxxxxxxxxxxx# OR pre-obtained access tokenLINEAR_ACCESS_TOKEN=lin_oauth_xxxxxxxxxxxx# OR single-tenant client credentials authLINEAR_CLIENT_CREDENTIALS_CLIENT_ID=your-client-idLINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET=your-client-secret# Optional, comma-separatedLINEAR_CLIENT_CREDENTIALS_SCOPES=read,write,comments:create,issues:create# OR multi-tenant OAuth installsLINEAR_CLIENT_ID=your-client-idLINEAR_CLIENT_SECRET=your-client-secretLINEAR_REDIRECT_URI=https://your-domain.com/api/linear/install/callback# Optional: encrypt stored OAuth tokens at restLINEAR_ENCRYPTION_KEY=...# Optional: inbound webhook mode# comments | agent-sessionsLINEAR_MODE=comments# RequiredLINEAR_WEBHOOK_SECRET=your-webhook-secret# Optional: override the Linear GraphQL API base URLLINEAR_API_URL=...
Features
Messaging
Feature
Supported
Post message
Yes
Edit message
Partial
Delete message
Partial
File uploads
No
Streaming
Agent sessions / Post+Edit fallback
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
Agent sessions only
DMs
No
Ephemeral messages
No
Message history
For agent-session threads, fetchMessages() throws a ValidationError if the session has no associated issue or its issue ID does not match the issue ID in the thread ID. The adapter checks this before fetching session comments or activities.
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
Comment threads are still comment-based — typing indicators and native streaming only exist for app-actor agent sessions
Agent session threads are append-only — editMessage and deleteMessage work for normal comments, but not for session activities
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
For app-actor mode, also enable Agent session events
Check that the webhook URL is correct and accessible
Ensure the userName config matches how users mention the bot
If using app-actor installs, ensure the app was installed with actor=app and app:mentionable
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
AI Coding Agents
If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chat
The skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-plugin
The plugin is optional; the skill alone is enough to build with Chat SDK.