Using Linear as a Tool or Trigger

Cosmos can plug into Linear as both a trigger source and a writable API. Listen for new issues, state changes, or slash-style comments; respond by reading or writing through linear-api.

Prerequisites

Linear has two integration flavors. Pick the one that matches how your Expert should act:

Flavor	Capability	When to use
Linear App (team install)	`LINEAR_APP`	Expert reads and writes Linear data using a team-level token shared across all Experts in the tenant
Linear user OAuth	`LINEAR`	Expert posts as the author who triggered it — e.g. a personal triage Expert running under your own credentials

To connect a team-wide install:

Go to Settings → Capabilities → Integrations from the Cosmos menu.
On the Linear tile, click Connect and complete the Linear Agent install flow.

To connect personal Linear OAuth:

Open Settings → Personal → Linked Accounts from the user menu.
On the Linear card, click Connect and complete the OAuth flow.

To remove a connection later, click Disconnect on the corresponding tile, or revoke the install from Linear’s Settings → API → Applications page. You can connect both — LINEAR_APP and LINEAR are independent, and different Experts in the same tenant can use either.

Enabling Linear as a Tool on an Expert

In the Expert editor, the Capabilities section lists every capability you can grant the Expert. Toggle on Linear App (or Linear for per-user) and save. Saving adds the linear-api tool to the Expert — a thin wrapper around Linear’s GraphQL API. Nothing else to configure. The capability mode determines authentication:

Linear App — requests are signed with the team-level Agent token
Linear — requests are signed with the invoking user’s OAuth token

Configuring Linear Triggers

Linear triggers are added from the Triggers section of the Expert editor. Pick Linear as the trigger type, set Event type to a Linear webhook type value (see below), and (optionally) write a Filter — a JSONLogic expression evaluated against the raw Linear webhook payload. The trigger fires only when the filter returns true. Top-level keys available to filter on: action, type, data, url, createdAt, organizationId, webhookTimestamp, webhookId. Available event types:

Issue, Comment, IssueLabel, Project, ProjectUpdate, Cycle, Reaction, Attachment — each with action ∈ create, update, remove

Triage Every New Issue in a Specific Team

Pick Event type Issue and filter on the action and team key:

{"and": [
  {"==": [{"var": "action"}, "create"]},
  {"==": [{"var": "data.team.key"}, "BUG"]}
]}

React to a Status Change

Pick Event type Issue and filter on the new state name:

{"and": [
  {"==": [{"var": "action"}, "update"]},
  {"==": [{"var": "data.state.name"}, "In Review"]}
]}

Slash-Style Command in Comments

Pick Event type Comment and match on the comment body:

{"and": [
  {"==": [{"var": "action"}, "create"]},
  {"in": ["/spec", {"var": "data.body"}]}
]}

Common Filter Recipes

// Action filtering
{"==": [{"var": "action"}, "create"]}
{"in": [{"var": "action"}, ["create", "update"]]}

// Team / project / cycle scoping
{"==": [{"var": "data.team.key"}, "ENG"]}
{"==": [{"var": "data.project.id"}, "<project-uuid>"]}
{"==": [{"var": "data.cycle.number"}, 42]}

// State and priority
{"==": [{"var": "data.state.name"}, "In Progress"]}
{"<=": [{"var": "data.priority"}, 2]}      // Urgent or High

// Label match
{"some": [{"var": "data.labels"}, {"==": [{"var": "name"}, "security"]}]}

// Skip the bot's own actions (avoid feedback loops)
{"!": [{"==": [{"var": "data.user.email"}, "agent@your-tenant.com"]}]}

A typo like data.statee.name silently never matches and the trigger will look broken. To test a filter against real Linear events, go to Settings → Automations → Event Log, filter by source = Linear and the event type you care about, and inspect the payload before saving the trigger.

Disabling Linear Access

You can scale back Linear access at three levels, from least to most disruptive:

Remove a single trigger. Delete the trigger row from the Expert editor and save. The Expert keeps the linear-api tool but no longer wakes up on that event.
Remove the Linear capability. Toggle off Linear App (or Linear) in the Expert’s Capabilities section. The Expert loses the linear-api tool and any remaining Linear triggers will be rejected when you save.
Disconnect the integration. From Settings → Capabilities → Integrations, click Disconnect on the Linear tile, or revoke the install from Linear’s Settings → API → Applications page. This revokes the token for every Expert in the tenant using that capability.

Getting Started

Cosmos

Auggie CLI

Other clients

Admin

Models & Pricing

Troubleshooting

Using Linear as a Tool or Trigger

Prerequisites

Enabling Linear as a Tool on an Expert

Configuring Linear Triggers

Triage Every New Issue in a Specific Team

React to a Status Change

Slash-Style Command in Comments

Common Filter Recipes

Disabling Linear Access

​Prerequisites

​Enabling Linear as a Tool on an Expert

​Configuring Linear Triggers

​Triage Every New Issue in a Specific Team

​React to a Status Change

​Slash-Style Command in Comments

​Common Filter Recipes

​Disabling Linear Access

Prerequisites

Enabling Linear as a Tool on an Expert

Configuring Linear Triggers

Triage Every New Issue in a Specific Team

React to a Status Change

Slash-Style Command in Comments

Common Filter Recipes

Disabling Linear Access