> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Bot

> Turn Linear into the task control plane for your coding agents

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Linear Agent Flow"
        A[📋 Linear Issue] --> B[📧 AgentSession Webhook]
        B --> C[🧠 LinearBot]
        C --> D[🤖 Agent Processing]
        D --> E[💬 Comment Response]
        E --> F[📊 Agent Activity]
    end
    
    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A input
    class B,C process
    class D agent
    class E,F result
```

## Quick Start

<Tabs>
  <Tab title="CLI">
    <Steps>
      <Step title="Set Environment Variables">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export LINEAR_OAUTH_TOKEN="your-linear-oauth-token"
        export LINEAR_WEBHOOK_SECRET="your-webhook-secret"
        ```
      </Step>

      <Step title="Start Linear Bot">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        praisonai bot linear --token $LINEAR_OAUTH_TOKEN --signing-secret $LINEAR_WEBHOOK_SECRET
        ```
      </Step>

      <Step title="Configure Linear Webhook">
        Configure your Linear webhook to point to `http://your-host:8080/webhook` with `AgentSession`, `Comment`, and `Issue` events enabled.
      </Step>
    </Steps>
  </Tab>

  <Tab title="YAML">
    <Steps>
      <Step title="Create Bot Configuration">
        ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # 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
        ```
      </Step>

      <Step title="Start from Configuration">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        praisonai bot start --config linear-bot.yaml
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python SDK">
    <Steps>
      <Step title="Create Agent with Linear Tools">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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,
        )
        ```
      </Step>

      <Step title="Start Linear Bot">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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())
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Linear Setup

<Steps>
  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Copy Signing Secret">
    Save the webhook signing secret for HMAC-SHA256 verification and 60-second replay protection.
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Linear
    participant LinearBot
    participant Agent
    participant GitHub
    
    User->>Linear: @bot or assign issue
    Linear->>LinearBot: AgentSession webhook
    LinearBot->>LinearBot: Verify HMAC signature
    LinearBot->>Agent: Process issue description
    Agent->>Agent: Plan solution steps
    Agent->>GitHub: Create branch & PR
    Agent->>LinearBot: Return response
    LinearBot->>Linear: Post comment
    LinearBot->>Linear: Create agent activity
```

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

<Note>
  OAuth tokens take precedence. If `LINEAR_OAUTH_TOKEN` is set, `LINEAR_API_KEY` is ignored.
</Note>

***

## 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](/docs/features/messaging-bots).

***

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

<Warning>
  Always set `LINEAR_WEBHOOK_SECRET` for production deployments. Missing secrets disable signature verification and log security warnings.
</Warning>

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       |

<Tip>
  See the complete [Linear tools documentation](/docs/tools/external/linear) for detailed usage examples.
</Tip>

***

## Common Patterns

<AccordionGroup>
  <Accordion title="Read-Only Triage Bot">
    Perfect for issue categorization and initial analysis without modifications:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent = Agent(
        name="Triage Assistant",
        instructions="Analyze incoming issues and provide initial categorization",
        tools=["linear_search_issues", "linear_add_comment"],
        auto_approve_tools=True
    )
    ```
  </Accordion>

  <Accordion title="Full Coder Bot with GitHub Integration">
    Complete development workflow from Linear issues to GitHub pull requests:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    )
    ```
  </Accordion>

  <Accordion title="Gateway Multi-Bot Setup">
    YAML configuration for gateway deployment:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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}
    ```
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Always Configure Webhook Secrets">
    Use `LINEAR_WEBHOOK_SECRET` to enable HMAC signature verification. This prevents replay attacks and ensures webhook authenticity.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Use HTTPS in Production">
    Deploy webhook endpoints behind HTTPS reverse proxies. Never expose HTTP webhook endpoints to the internet.
  </Accordion>

  <Accordion title="Rotate Secrets Regularly">
    Implement secret rotation for both OAuth tokens and webhook secrets. Update Linear webhook configurations when rotating.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Messaging Bots" icon="comments" href="/docs/features/messaging-bots">
    Platform support and bot protocols
  </Card>

  <Card title="Bot Gateway" icon="globe" href="/docs/features/bot-gateway">
    Multi-platform bot orchestration
  </Card>

  <Card title="Linear Tools" icon="wrench" href="/docs/tools/external/linear">
    Complete Linear API tool reference
  </Card>

  <Card title="CLI Bot Command" icon="terminal" href="/docs/cli/bot">
    Command-line bot management
  </Card>
</CardGroup>