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

# Using Linear as a Tool or Trigger

> Configure Linear triggers and the Linear API tool on your Cosmos Experts — listen for issues, status changes, and comments.

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:

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](https://jsonlogic.com) 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:

```json theme={null}
{"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:

```json theme={null}
{"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:

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

### Common Filter Recipes

```json theme={null}
// 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"]}]}
```

<Tip>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.</Tip>

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