Linear Bot

Turn Linear into the task control plane for your coding agents

from praisonaiagents import Agent

agent = Agent(name="linear-bot", instructions="Manage Linear issues and projects.")
agent.start("Create a new Linear issue: Fix the login bug in production.")

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

The user mentions or assigns a Linear issue; the bot webhook runs your agent and posts the reply back to the thread.

Quick Start

CLI

1. Set Environment Variables

   export LINEAR_OAUTH_TOKEN="your-linear-oauth-token"
   export LINEAR_WEBHOOK_SECRET="your-webhook-secret"
   
2. Start Linear Bot

   praisonai bot linear --token $LINEAR_OAUTH_TOKEN --signing-secret $LINEAR_WEBHOOK_SECRET
   
3. Configure Linear Webhook

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

YAML

1. 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
   
2. Start from Configuration

   praisonai bot start --config linear-bot.yaml
   

Python SDK

1. 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,
   )
   
2. 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

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

2. 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)
3. 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:

1. Receives webhook → AgentSession event triggers the bot
2. Analyzes issue → Reads title, description, and acceptance criteria
3. Plans implementation → Breaks down into authentication middleware, tests, docs
4. Posts status comment → “Working on authentication implementation…”
5. Executes solution → Creates GitHub branch, writes code, adds tests
6. Updates Linear → Comments with PR link and implementation summary
7. 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 cause inbound webhooks to be rejected with HTTP 401 (fail-closed). Set PRAISONAI_INSECURE_WEBHOOKS=true only for local development.

The bot implements Linear’s recommended security measures via the shared Webhook Verification stack:

• 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

Set LINEAR_WEBHOOK_SECRET for HMAC verification. Without it, webhooks are rejected with HTTP 401. Use PRAISONAI_INSECURE_WEBHOOKS=true only for local development. See Webhook Verification.

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.

---

Related

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