@chat-adapter/linear weekly downloads statistics

@chat-adapter/linear

npm package: @chat-adapter/linear

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

Installation

pnpm add @chat-adapter/linear

Scaffold with the CLI

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",
});

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