Skip to main content
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

Agent Sessions

@mention or assign Cotool in Linear issues to trigger agents with real-time streaming responses.

Issue Management

Create, update, and comment on Linear issues programmatically from any agent.

Live Progress

See agent reasoning, tool actions, and plan steps streamed directly into the Linear issue thread.

Conversation Continuity

Follow up in the same thread — the agent picks up full context from previous messages.

​
Setup

1

Navigate to Integrations

Go to Settings > Integrations in Cotool and find the Linear integration.
2

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

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

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

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

Agent Acknowledges

Cotool immediately responds with a “Thinking…” status so you know your request was received.
3

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
4

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.

​
Agent Triggers vs. Personal Chats

Cotool supports two modes when receiving a Linear Agent Session event, similar to how the Slack integration 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.
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.

​
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
Deterministic chat IDs ensure that follow-up messages always map back to the same Cotool conversation, so context is never lost between turns.

​
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:
1

Create or Edit an Agent

Navigate to the agent you want to trigger from Linear.
2

Add a Linear Trigger

In the agent’s Triggers tab, click Add Trigger and select Linear.
3

Select Agent Session Mode

Choose Agent Session mode (the default). This uses Linear’s native agent protocol instead of legacy issue-created webhooks.
4

Save the Trigger

Save the trigger. Cotool will now handle all Linear Agent Session events for your workspace using this agent.
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.

​
Available Tools

When an agent has the Linear integration enabled, it can use these tools:
ToolDescription
linear_createIssueCreate a new issue in a Linear project
linear_getIssueGet details of a Linear issue by ID
linear_addCommentToIssueAdd a comment to an existing issue
linear_listStatusesList all available statuses for issues
linear_updateIssueStatusUpdate the status of an issue
linear_listMyIssuesList issues assigned to a user

​
Example Use Cases

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

​
Best Practices

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.
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.
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”).
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.