Skip to main content
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:
FlavorCapabilityWhen to use
Linear App (team install)LINEAR_APPExpert reads and writes Linear data using a team-level token shared across all Experts in the tenant
Linear user OAuthLINEARExpert posts as the author who triggered it — e.g. a personal triage Expert running under your own credentials
To connect a team-wide install:
  1. Go to Configuration → Integrations in the sidebar.
  2. On the Linear tile, click Connect and complete the Linear Agent install flow.
To connect personal Linear OAuth:
  1. Open My settings → Integrations from the user menu.
  2. 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 Configuration → Events 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:
  1. 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.
  2. 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.
  3. Disconnect the integration. From Configuration → 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.