vercel__chat/packages/adapter-linear

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

Installation

pnpm add @chat-adapter/linear

Usage

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

By default, the adapter runs in mode: "comments" and treats Comment webhooks as the inbound message source. For Linear app-actor installs, set mode: "agent-sessions" so inbound handling is driven by AgentSessionEvent.

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: Pre-obtained OAuth access token

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

Option C: Multi-tenant OAuth installs

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.

1. Go to Settings > API > Applications
2. Create an OAuth2 application with your bot's name and icon
3. Note the Client ID and Client Secret

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

Option D: 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.

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

Token encryption

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:

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,issues:create,app:mentionable&
  actor=app

If 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 event
• thread.startTyping() sends an ephemeral Linear thought
• thread.post(stream) uses agent activities and session plan updates
• Session threads are append-only, so sent.edit() / sent.delete() are not supported there

See the Linear Agents docs for full details.

Direct API client

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

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 for mode: "comments")
   • Agent session events (required for mode: "agent-sessions")
   • 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 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

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*	Pre-obtained OAuth access token. 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. "comments" by default, or "agent-sessions" for app-actor installs
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")
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, top-level clientId/clientSecret, or clientCredentials 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 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=...

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

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

License

MIT