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

# Linear Integration

> Connect Cotool to Linear for issue tracking and AI agent sessions

The Linear integration enables your AI agents to work directly inside Linear. Agents can manage issues, respond to @mentions and assignments, stream real-time progress updates, and be triggered by Linear Agent Sessions — all without leaving your project management workflow.

## Features

<CardGroup cols={2}>
  <Card title="Agent Sessions" icon="robot">
    @mention or assign Cotool in Linear issues to trigger agents with real-time streaming responses.
  </Card>

  <Card title="Issue Management" icon="list-check">
    Create, update, and comment on Linear issues programmatically from any agent.
  </Card>

  <Card title="Live Progress" icon="spinner">
    See agent reasoning, tool actions, and plan steps streamed directly into the Linear issue thread.
  </Card>

  <Card title="Conversation Continuity" icon="comments">
    Follow up in the same thread — the agent picks up full context from previous messages.
  </Card>
</CardGroup>

## Setup

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Settings > Integrations** in Cotool and find the Linear integration.
  </Step>

  <Step title="Connect Linear">
    Click **Connect** to authenticate. Cotool will register as an app-actor in your Linear workspace, enabling it to be assigned to and mentioned in issues.
  </Step>

  <Step title="Verify Permissions">
    The integration requires the following scopes:

    * Read and write access to issues and comments
    * App assignable (Cotool can be assigned to issues)
    * App mentionable (Cotool can be @mentioned in issues)
  </Step>
</Steps>

<Note>
  If you previously connected Linear before the Agent Session feature was available, you'll see a prompt to **Reconnect** to upgrade your credentials. This upgrades to app-actor credentials that support assignment and mentions.
</Note>

## How It Works

### Linear Agent Sessions

Linear Agent Sessions are the primary way to interact with Cotool from within Linear. When you @mention or assign Cotool on a Linear issue, Linear creates an Agent Session and sends a webhook to Cotool. Cotool then processes the request and streams its response directly back into the issue thread.

<Steps>
  <Step title="Trigger Cotool in Linear">
    @mention Cotool or assign it to an issue in Linear. You can include a description of what you'd like the agent to do.
  </Step>

  <Step title="Agent Acknowledges">
    Cotool immediately responds with a "Thinking..." status so you know your request was received.
  </Step>

  <Step title="Live Progress Updates">
    As the agent works, you'll see real-time updates streamed into the Linear thread:

    * **Thoughts** — the agent's reasoning process
    * **Actions** — tool calls the agent makes (e.g., querying a SIEM, checking an EDR)
    * **Plan steps** — if the agent creates a plan, each step and its status syncs to Linear's Agent Plan UI
  </Step>

  <Step title="Final Response">
    When the agent completes, its final summary is posted as a response in the thread, along with a link to view the full run in Cotool.
  </Step>
</Steps>

### Agent Triggers vs. Personal Chats

Cotool supports two modes when receiving a Linear Agent Session event, similar to how the [Slack integration](/integrations/communication/slack) handles channels vs. DMs:

**Agent Triggers (Recommended)**

When a Linear Agent Session trigger is configured on an agent, that agent handles all incoming requests from your Linear workspace. This is the recommended setup for teams.

**Personal Chats (Fallback)**

If no agent trigger is configured, Cotool falls back to creating a personal chat for the requesting user. The user's Linear email must match a Cotool account. This is useful for ad-hoc queries without a dedicated agent.

<Warning>
  Personal chats require a matching Cotool account. If no account is found for the Linear user's email, Cotool will respond with an error message in the Linear thread.
</Warning>

### Conversation Continuity

When you send a follow-up message in a Linear Agent Session thread, Cotool continues the existing conversation with full context of the previous exchange. This enables multi-turn interactions:

1. @mention Cotool: *"Investigate the suspicious login from IP 10.0.0.5"*
2. Agent responds with findings
3. Follow up: *"Can you also check if this IP appears in any other alerts?"*
4. Agent continues with the new request, retaining context from step 2

<Tip>
  Deterministic chat IDs ensure that follow-up messages always map back to the same Cotool conversation, so context is never lost between turns.
</Tip>

### Stopping an Agent

If an agent is taking too long or you want to cancel a request, you can stop it directly from Linear. Cotool will:

1. Interrupt the running agent execution
2. Acknowledge the stop in the Linear thread with a confirmation message
3. Mark the chat as interrupted in Cotool

## Setting Up an Agent Trigger

To route Linear Agent Sessions to a specific agent:

<Steps>
  <Step title="Create or Edit an Agent">
    Navigate to the agent you want to trigger from Linear.
  </Step>

  <Step title="Add a Linear Trigger">
    In the agent's **Triggers** tab, click **Add Trigger** and select **Linear**.
  </Step>

  <Step title="Select Agent Session Mode">
    Choose **Agent Session** mode (the default). This uses Linear's native agent protocol instead of legacy issue-created webhooks.
  </Step>

  <Step title="Save the Trigger">
    Save the trigger. Cotool will now handle all Linear Agent Session events for your workspace using this agent.
  </Step>
</Steps>

<Note>
  **Legacy webhook mode** is still available for backward compatibility. Legacy triggers fire when a Linear issue is created and require manual webhook configuration. New triggers should use Agent Session mode.
</Note>

## Available Tools

When an agent has the Linear integration enabled, it can use these tools:

| Tool                       | Description                            |
| -------------------------- | -------------------------------------- |
| `linear_createIssue`       | Create a new issue in a Linear project |
| `linear_getIssue`          | Get details of a Linear issue by ID    |
| `linear_addCommentToIssue` | Add a comment to an existing issue     |
| `linear_listStatuses`      | List all available statuses for issues |
| `linear_updateIssueStatus` | Update the status of an issue          |
| `linear_listMyIssues`      | List issues assigned to a user         |

## Example Use Cases

<AccordionGroup>
  <Accordion title="Security Alert Triage">
    Create an agent that, when @mentioned on a Linear issue, automatically investigates the referenced alert — querying your SIEM, checking EDR telemetry, and summarizing findings directly in the issue thread.
  </Accordion>

  <Accordion title="Incident Response Coordinator">
    Assign Cotool to an incident ticket in Linear. The agent gathers context from Datadog, PagerDuty, and Slack, then posts a structured summary with recommended next steps.
  </Accordion>

  <Accordion title="Access Review Assistant">
    @mention Cotool on access review tickets to have it check Okta group memberships, verify last login dates, and recommend whether access should be renewed or revoked.
  </Accordion>

  <Accordion title="Detection Engineering Support">
    When creating a new detection rule ticket, @mention Cotool to have it research similar detections, check MITRE ATT\&CK mappings, and draft an initial detection rule.
  </Accordion>
</AccordionGroup>

## Best Practices

<Tip>
  **Use agent triggers for team workflows** — Configure an Agent Session trigger on a dedicated agent so your entire team gets consistent behavior when interacting with Cotool in Linear.
</Tip>

<Tip>
  **Leverage plan syncing** — Agents that use the `todo_write` tool will have their plan steps automatically synced to Linear's Agent Plan UI, giving you visibility into the agent's progress at a glance.
</Tip>

<Tip>
  **Keep agent prompts Linear-aware** — Agents triggered from Linear automatically receive context instructions, but you can further customize behavior by mentioning Linear in your agent's system prompt (e.g., "When triggered from Linear, always include a summary at the end").
</Tip>

<Tip>
  **Reconnect if prompted** — If you see a "Reconnect" banner on the Linear integration page, reconnect to upgrade to the latest app-actor credentials. This enables assignment, mentions, and agent session features.
</Tip>