Linear Integration

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

Navigate to Integrations

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

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.

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.

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.

Agent Acknowledges

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

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

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) One enabled Linear Agent Session trigger acts as the default for your organization. Its agent handles Agent Sessions created by @mentions and assignments from your Linear workspace. Only one Linear Agent Session trigger can be enabled at a time. External automation can use that trigger as the Linear transport while routing individual sessions to any agent in the organization. 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:

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

Each Linear Agent Session stays bound to the Cotool chat created for it. Follow-ups and stop requests return to that same agent and conversation.

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:

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

Setting Up an Agent Trigger

To route Linear Agent Sessions to a specific agent:

Create or Edit an Agent

Navigate to the agent you want to trigger from Linear.

Add a Linear Trigger

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

Select Agent Session Mode

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

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.

Routing Different Agents from External Automation

If an external system such as Tines already decides which agent should triage an issue, use the agent-specific endpoint to start the Linear Agent Session:

curl -X POST "https://app.cotool.ai/api/agents/$AGENT_ID/linear/agent-session" \
  -H "Authorization: Bearer $COTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issueId": "ITM-123"
  }'

Cotool creates the Linear Agent Session on the issue and binds it to the selected agent’s chat. Progress and the final response appear in Linear. Replies and stop requests in that Agent Session return to the same agent with the existing conversation context.

Configure Multiple Agent Entry Points

Configure one enabled Agent Session Linear trigger as the default for direct @mentions and assignments.
Create or select the agents that external automation may invoke. These targeted agents do not need their own Linear triggers.
In Tines, call the endpoint with the selected agent’s ID and the Linear issue ID or identifier.

The request body supports:

Field	Required	Description
`issueId`	Yes	Linear issue UUID or identifier, such as `ITM-123`
`externalUrls`	No	Links to related resources to display in the Linear Agent Session

Example response:

{
    "success": true,
    "message": "Linear agent session created.",
    "agentSessionId": "2b08de70-1d3d-4f2f-b972-13bb4ab21bcb",
    "triggerId": "9b1bd0df-a87f-49cf-a649-889ee748982d"
}

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_addLabelsToIssue`	Add existing Linear labels to an 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
`linear_listTeamIssues`	List active issues for a team

Example Use Cases

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.

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.

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.

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.

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.

Getting Started

Core Concepts

Chat

Agents

Triage

Hunt

Log Ingest

Detections

Improving Agents

Settings

Integrations

Features

Agent Sessions

Issue Management

Live Progress

Conversation Continuity

Setup

How It Works

Linear Agent Sessions

Agent Triggers vs. Personal Chats

Conversation Continuity

Stopping an Agent

Setting Up an Agent Trigger

Routing Different Agents from External Automation

Configure Multiple Agent Entry Points

Available Tools

Example Use Cases

Best Practices

​Features

Agent Sessions

Issue Management

Live Progress

Conversation Continuity

​Setup

​How It Works

​Linear Agent Sessions

​Agent Triggers vs. Personal Chats

​Conversation Continuity

​Stopping an Agent

​Setting Up an Agent Trigger

​Routing Different Agents from External Automation

​Configure Multiple Agent Entry Points

​Available Tools

​Example Use Cases

​Best Practices

Features

Setup

How It Works

Linear Agent Sessions

Agent Triggers vs. Personal Chats

Conversation Continuity

Stopping an Agent

Setting Up an Agent Trigger

Routing Different Agents from External Automation

Configure Multiple Agent Entry Points

Available Tools

Example Use Cases

Best Practices