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
- Set Environment Variables
bash export LINEAR_OAUTH_TOKEN="your-linear-oauth-token" export LINEAR_WEBHOOK_SECRET="your-webhook-secret" - Start Linear Bot
bash 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/webhookwithAgentSession,Comment, andIssueevents enabled.
YAML
- Create Bot Configuration
yaml # linear-bot.yaml platform: linear token: ${LINEAR_OAUTH_TOKEN} signing_secret: ${LINEAR_WEBHOOK_SECRET} webhook_port: 8080 # Linear always binds its own server 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
bash praisonai bot start --config linear-bot.yaml
Python SDK
- Create Agent with Linear Tools
python 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
python 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
Bearerprefix; API keys are sent raw. - Configure Webhook
Set up a webhook pointing to
https://your-host:8080/webhookwith 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 |
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 Linear’s own webhook HTTP server (Linear always binds its own 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
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 |
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=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.