Linear Bot

Connect your AI agent to Linear so it acts on issue mentions and assignments — replying with comments, updating issues, and emitting agent activities.

Quick Start

CLI
YAML
Python SDK

Set Environment Variables

export LINEAR_OAUTH_TOKEN="your-linear-oauth-token"
export LINEAR_WEBHOOK_SECRET="your-webhook-secret"

Start Linear Bot

praisonai bot linear --token $LINEAR_OAUTH_TOKEN --signing-secret $LINEAR_WEBHOOK_SECRET

Configure Linear Webhook

Configure your Linear webhook to point to http://your-host:8080/webhook with AgentSession, Comment, and Issue events enabled.

Create Bot Configuration

# linear-bot.yaml
platform: linear
token: ${LINEAR_OAUTH_TOKEN}
signing_secret: ${LINEAR_WEBHOOK_SECRET}
webhook_port: 8080

agent:
  name: "PraisonAI Coder"
  instructions: |
    You are an autonomous coding agent integrated with Linear.
    
    When you are mentioned or assigned an issue:
    1. Analyze the issue description and requirements
    2. Break down complex tasks into smaller steps
    3. Use available tools to implement solutions
    4. Update the issue with progress comments
    5. Create GitHub pull requests when code changes are needed
  llm: gpt-4o-mini
  tools:
    - linear_search_issues
    - linear_get_issue
    - linear_add_comment
    - linear_update_issue
    - linear_list_teams
    - linear_list_issue_states
    - github_create_branch
    - github_commit_and_push
    - github_create_pull_request
    - read_file
    - write_file
  memory: true
  auto_approve_tools: true

Start from Configuration

praisonai bot start --config linear-bot.yaml

Create Agent with Linear Tools

from praisonaiagents import Agent
from praisonai.bots import LinearBot

agent = Agent(
    name="PraisonAI Coder",
    instructions="""
    You are an autonomous coding agent integrated with Linear.
    
    When you are mentioned or assigned an issue:
    1. Analyze the issue description and requirements
    2. Break down complex tasks into smaller steps
    3. Use available tools to implement solutions
    4. Update the issue with progress comments
    5. Create GitHub pull requests when code changes are needed
    """,
    llm="gpt-4o-mini",
    tools=[
        "linear_search_issues",
        "linear_get_issue", 
        "linear_add_comment",
        "linear_update_issue",
        "linear_list_teams",
        "linear_list_issue_states",
        "github_create_branch",
        "github_commit_and_push",
        "read_file",
        "write_file"
    ],
    memory=True,
    auto_approve_tools=True,
)

Start Linear Bot

import asyncio

bot = LinearBot(
    token="your-linear-oauth-token",
    signing_secret="your-webhook-secret", 
    agent=agent,
    webhook_port=8080,
)

async def main():
    await bot.start()

asyncio.run(main())

Linear Setup

Create OAuth App or API Key

In Linear, go to Settings → API → Create OAuth App or Personal API Key. OAuth tokens require Bearer prefix; API keys are sent raw.

Configure Webhook

Set up a webhook pointing to https://your-host:8080/webhook with these events:

AgentSession (for mentions/assignments)
Comment (for comment threads)
Issue (for issue updates)

Copy Signing Secret

Save the webhook signing secret for HMAC-SHA256 verification and 60-second replay protection.

How It Works

Step	Description
Webhook Reception	Linear sends AgentSession webhook when bot is mentioned or assigned
Signature Verification	HMAC-SHA256 signature check with 60-second timestamp validation
Issue Processing	Agent analyzes issue title, description, and requirements
Tool Execution	Agent uses Linear and GitHub tools to implement solutions
Response Delivery	Bot posts comments back to Linear with progress updates

User Interaction Flow

Alice assigns issue ENG-42 “Add user authentication to API” to the bot. The bot:

Receives webhook → AgentSession event triggers the bot
Analyzes issue → Reads title, description, and acceptance criteria
Plans implementation → Breaks down into authentication middleware, tests, docs
Posts status comment → “Working on authentication implementation…”
Executes solution → Creates GitHub branch, writes code, adds tests
Updates Linear → Comments with PR link and implementation summary
Creates activity → Records bot response in Linear’s agent activity log

OAuth vs API Key Authentication

Auth Type	Header Format	Use Case
OAuth Token	`Authorization: Bearer <token>`	Team integrations, shared bots
Personal API Key	`Authorization: <key>` (raw)	Individual developer bots

OAuth tokens take precedence. If LINEAR_OAUTH_TOKEN is set, LINEAR_API_KEY is ignored.

Configuration Options

Option	Type	Default	Description
`token`	`str`	`""`	Linear OAuth token or API key
`agent`	`Agent`	`None`	Agent instance to handle messages
`config`	`BotConfig`	Auto-created	Bot configuration object
`signing_secret`	`str`	`""`	Webhook HMAC verification secret
`webhook_port`	`int`	`8080`	Port for webhook HTTP server
`webhook_path`	`str`	`"/webhook"`	Path for webhook endpoint

For complete bot configuration options, see the messaging bots documentation.

Built-in Commands

The Linear bot includes these slash commands:

Command	Description
`/status`	Show bot status, uptime, and Linear connection info
`/new`	Reset conversation session and start fresh
`/help`	Display available commands and bot capabilities

Webhook Security

Always set LINEAR_WEBHOOK_SECRET for production deployments. Missing secrets disable signature verification and log security warnings.

The bot implements Linear’s recommended security measures:

HMAC-SHA256 signature verification using webhook secret
60-second replay protection via timestamp validation
HTTPS enforcement recommended for production webhooks

Linear Tools

The following Linear tools work with the bot for comprehensive issue management:

Tool	Description
`linear_search_issues`	Search Linear issues by text, status, or team
`linear_get_issue`	Get detailed issue information by ID
`linear_add_comment`	Add comments to Linear issues
`linear_update_issue`	Update issue status, assignee, or properties
`linear_list_teams`	List all teams in the Linear workspace
`linear_list_issue_states`	Get available issue states for workflow

See the complete Linear tools documentation for detailed usage examples.

Common Patterns

Read-Only Triage Bot

Perfect for issue categorization and initial analysis without modifications:

agent = Agent(
    name="Triage Assistant",
    instructions="Analyze incoming issues and provide initial categorization",
    tools=["linear_search_issues", "linear_add_comment"],
    auto_approve_tools=True
)

Full Coder Bot with GitHub Integration

Complete development workflow from Linear issues to GitHub pull requests:

agent = Agent(
    name="PraisonAI Coder", 
    instructions="Implement solutions for Linear issues",
    tools=[
        "linear_search_issues", "linear_get_issue", "linear_add_comment",
        "linear_update_issue", "github_create_branch", "github_commit_and_push",
        "github_create_pull_request", "read_file", "write_file", "execute_command"
    ],
    memory=True,
    web_search=True
)

Gateway Multi-Bot Setup

YAML configuration for gateway deployment:

platform: linear
channels:
  - name: "engineering"
    token: ${LINEAR_ENG_TOKEN}
    signing_secret: ${LINEAR_ENG_SECRET}
  - name: "design" 
    token: ${LINEAR_DESIGN_TOKEN}
    signing_secret: ${LINEAR_DESIGN_SECRET}

Best Practices

Always Configure Webhook Secrets

Use LINEAR_WEBHOOK_SECRET to enable HMAC signature verification. This prevents replay attacks and ensures webhook authenticity.

Scope OAuth Tokens Appropriately

Grant minimum required permissions. For read-only bots, use tokens with limited scopes. For coding bots, ensure write access to issues and comments.

Use HTTPS in Production

Deploy webhook endpoints behind HTTPS reverse proxies. Never expose HTTP webhook endpoints to the internet.

Rotate Secrets Regularly

Implement secret rotation for both OAuth tokens and webhook secrets. Update Linear webhook configurations when rotating.

Messaging Bots

Platform support and bot protocols

Bot Gateway

Multi-platform bot orchestration

Linear Tools

Complete Linear API tool reference

CLI Bot Command

Command-line bot management

Getting Started

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Linear Setup

How It Works

User Interaction Flow

OAuth vs API Key Authentication

Configuration Options

Built-in Commands

Webhook Security

Linear Tools

Common Patterns

Best Practices

Messaging Bots

Bot Gateway

Linear Tools

CLI Bot Command

Getting Started

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Documentation Index

​Quick Start

​Linear Setup

​How It Works

​User Interaction Flow

​OAuth vs API Key Authentication

​Configuration Options

​Built-in Commands

​Webhook Security

​Linear Tools

​Common Patterns

​Best Practices

​Related

Messaging Bots

Bot Gateway

Linear Tools

CLI Bot Command

Quick Start

Linear Setup

How It Works

User Interaction Flow

OAuth vs API Key Authentication

Configuration Options

Built-in Commands

Webhook Security

Linear Tools

Common Patterns

Best Practices

Related