package
Linear adapter for Chat SDK — @mentions in issue comments and Linear agent sessions
npm install @chat-adapter/linearGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
Linear adapter for Chat SDK. Respond to @mentions in issue comment threads and Linear app-actor agent sessions.
The Linear adapter treats issue comments as messages and issues as threads.
Documentation: chat-sdk.dev/adapters/official/linear · Guides: vercel.com/kb/chat-sdk
pnpm add @chat-adapter/linearTo scaffold a new Linear bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter linear memoryVisit the adapters directory to see other available official and vendor-official adapters.
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.
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.
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",
});Or wire the fields yourself:
import { getToken } from "@vercel/connect";
createLinearAdapter({
accessToken: () =>
getToken("linear/acme-linear", { subject: { type: "app" } }),
webhookVerifier: myConnectWebhookVerifier,
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 mintimestamp rejection, and there is no built-in delivery de-duplication. Keep your webhook handlers idempotent (Linear can also deliver events out of order).
Best for personal projects, testing, or single-workspace bots. Actions are attributed to you as an individual.
LINEAR_API_KEYcreateLinearAdapter({
apiKey: process.env.LINEAR_API_KEY!,
});Use this when your app already manages the OAuth flow and you just want the adapter to operate with a single workspace token.
createLinearAdapter({
accessToken: process.env.LINEAR_ACCESS_TOKEN!,
});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.
const adapter = createLinearAdapter({
clientId: process.env.LINEAR_CLIENT_ID!,
clientSecret: process.env.LINEAR_CLIENT_SECRET!,
mode: "agent-sessions",
});Example callback route:
await bot.initialize();
const { organizationId } = await adapter.handleOAuthCallback(request, {
redirectUri: process.env.LINEAR_REDIRECT_URI!,
});Example background job:
await adapter.withInstallation("org-id", async () => {
await adapter.postMessage("linear:issue-id", "Hello from a background job");
});If you want app identity without multi-tenant installs, use the explicit clientCredentials config. The adapter fetches and refreshes the token automatically.
createLinearAdapter({
clientCredentials: {
clientId: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_ID!,
clientSecret: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET!,
scopes: ["read", "write", "comments:create", "issues:create"],
},
mode: "agent-sessions",
});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 32When 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).
To make the bot appear in Linear's @ mention dropdown as an Agent:
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,issues:create,app:mentionable&
actor=appIf you use single-tenant client credentials, request the same scopes there:
createLinearAdapter({
clientCredentials: {
clientId: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_ID!,
clientSecret: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET!,
scopes: [
"read",
"write",
"comments:create",
"issues:create",
"app:mentionable",
],
},
});Once installed with actor=app, set mode: "agent-sessions" so the adapter treats AgentSessionEvent as the entrypoint for mentions:
onNewMention fires from the session-created eventthread.startTyping() sends an ephemeral Linear thoughtthread.post(stream) uses agent activities and session plan updatessent.edit() / sent.delete() are not supported thereSee the Linear Agents docs for full details.
For anything beyond the unified SDK, access the underlying LinearClient via .linearClient:
const linear = bot.getAdapter("linear").linearClient;
const issue = await linear.issue("ENG-123");
const project = await issue.project;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
.clientgetter still works as a deprecated alias for.linearClient.
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.
https://your-domain.com/api/webhooks/linearLINEAR_WEBHOOK_SECRETmode: "comments")mode: "agent-sessions")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.
| SDK emoji | Linear emoji |
|---|---|
thumbs_up | thumbs_up |
thumbs_down | thumbs_down |
heart | heart |
fire | fire |
rocket | rocket |
eyes | eyes |
sparkles | sparkles |
wave | wave |
# API Key auth
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
# OR pre-obtained access token
LINEAR_ACCESS_TOKEN=lin_oauth_xxxxxxxxxxxx
# OR single-tenant client credentials auth
LINEAR_CLIENT_CREDENTIALS_CLIENT_ID=your-client-id
LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET=your-client-secret
# Optional, comma-separated
LINEAR_CLIENT_CREDENTIALS_SCOPES=read,write,comments:create,issues:create
# OR multi-tenant OAuth installs
LINEAR_CLIENT_ID=your-client-id
LINEAR_CLIENT_SECRET=your-client-secret
LINEAR_REDIRECT_URI=https://your-domain.com/api/linear/install/callback
# Optional: encrypt stored OAuth tokens at rest
LINEAR_ENCRYPTION_KEY=...
# Optional: inbound webhook mode
# comments | agent-sessions
LINEAR_MODE=comments
# Required
LINEAR_WEBHOOK_SECRET=your-webhook-secret
# Optional: override the Linear GraphQL API base URL
LINEAR_API_URL=...| Feature | Supported |
|---|---|
| Post message | Yes |
| Edit message | Partial |
| Delete message | Partial |
| File uploads | No |
| Streaming | Agent sessions / Post+Edit fallback |
| Feature | Supported |
|---|---|
| Card format | Markdown |
| Buttons | No |
| Link buttons | No |
| Select menus | No |
| Tables | GFM |
| Fields | Yes |
| Images in cards | No |
| Modals | No |
| Feature | Supported |
|---|---|
| Slash commands | No |
| Mentions | Yes |
| Add reactions | Yes |
| Remove reactions | Partial |
| Typing indicator | Agent sessions only |
| DMs | No |
| Ephemeral messages | No |
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 |
editMessage and deleteMessage work for normal comments, but not for session activitiesLINEAR_WEBHOOK_SECRET matches the secret from your webhook configurationuserName config matches how users mention the botactor=app and app:mentionableIf 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/chatThe 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-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
Estimated unpacked size across 26 packages.
10.5 MB
Includes dependencies.
3 direct · 1 outdated