> ## Documentation Index > Fetch the complete documentation index at: https://atcyrus.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Linear > How Cyrus integrates with Linear: assigned issues, label triggers, and comment mentions Linear is Cyrus's primary workspace. Assign an issue, add a label, or mention Cyrus in a comment. The agent picks up the work, posts progress back to the ticket, and opens a pull request when it's done. *** ## Overview Once connected, Cyrus can be triggered from Linear in three ways: * **Assign an issue to Cyrus.** The agent starts working immediately. * **Create an issue with an auto-assign label.** With **Auto-assign by Label** enabled, any new issue that's created with one of your configured labels is automatically delegated to Cyrus, no manual assignment needed. * **Mention Cyrus in a comment.** Ad-hoc instructions on any ticket. Activity streams back to the issue in real time: a live feed of what the agent is doing, status changes as work progresses, and links to the pull request and session when the work is complete. Manage everything from the [Cyrus dashboard](https://app.atcyrus.com/settings/integrations). *** ## Setup Linear is connected during the onboarding wizard, but you can also connect it (or reconnect) from your [Integrations settings](https://app.atcyrus.com/settings/integrations). Click **Connect Linear** in the Linear integration card. You'll be redirected to Linear to authorize the Cyrus OAuth application. Approve the requested scopes. Cyrus needs them to read issues, comment, update status, and apply labels on your behalf. Choose which Linear teams Cyrus should monitor. Only issues from selected teams will trigger sessions. You can change this later from the dashboard. Open [Settings → Behaviours](https://app.atcyrus.com/settings/behaviours) and configure **Auto-assign by Label** if you want new issues with specific labels to be picked up automatically. See [Configuration](#configuration) below. Each Cyrus workspace connects to exactly one Linear workspace. If you operate in multiple Linear workspaces, add another Cyrus workspace from the workspace switcher (top-left, below the logo) and switch between them at any time. ### Permissions Cyrus requests | Scope | Why Cyrus needs it | | ---------------------- | -------------------------------------------------------------------------- | | **Read issues** | Fetch the issue body, labels, project, and team to plan the work | | **Read comments** | Pick up `@cyrus` mentions and replies in the agent thread | | **Write comments** | Post progress updates, summaries, and PR links back to the ticket | | **Update issues** | Transition status (e.g. `In Progress` → `In Review`) as work moves forward | | **Read users / teams** | Resolve assignees, attribute work, and route by team | | **Read labels** | Detect auto-assign labels on new issues | *** ## How to trigger Cyrus from Linear ### Assign an issue The simplest trigger. Assign any issue to the Cyrus user in your Linear workspace and the agent will: 1. Read the issue title, description, attachments, and thread 2. Route the issue to the correct repository (see [Labels and Routing](/labels-and-routing)) 3. Open a Git worktree, start a session, and post a live activity feed to the ticket 4. Transition the issue through `In Progress` → `In Review` 5. Open a pull request and link it back on the ticket The issue's labels and project determine *which* repository the work happens in and *how* Cyrus approaches it. See [Labels and Routing](/labels-and-routing) for the full priority order. ### Create an issue with an auto-assign label Auto-assign by Label lets you delegate work to Cyrus by tagging the issue, rather than explicitly assigning the agent. Pick any labels that already exist in your Linear workspace (e.g. `cyrus`, `bug`, `agent-ready`) and tell Cyrus to treat them as triggers. Configure this under [Settings → Behaviours](https://app.atcyrus.com/settings/behaviours), in the **Auto-assign by Label** card. Click **Configure Labels**, tick the labels you want to use, and save. The matched labels are stored at the team level and used across your workspace. #### How the trigger fires When a new issue is created in a connected Linear team: 1. Linear sends a webhook to Cyrus with the new issue payload. 2. Cyrus checks the issue's labels against the auto-assign list for the team (case-insensitive match). 3. If a label matches and the issue isn't already assigned or delegated, Cyrus delegates the issue to itself via Linear's agent-session API and starts a session. 4. Cyrus posts a thought to the session noting that the run was triggered by the matched label, and links back to the Behaviours page so admins can change the rule later. If no labels are configured, or **Auto-assign by Label** has no matches for the issue, nothing happens. Existing issues that have a label added *after* creation are not retroactively delegated; the trigger fires on issue creation only, to avoid double-firing when create and update webhooks arrive in quick succession. Use [@mentions](#mention-cyrus-in-a-comment) or an explicit assignment to trigger work on issues that are already open. #### When to use it * **Triage workflows.** Anyone on the team can drop a label like `cyrus` on a new bug and the agent picks it up without waiting for an assignment. * **Severity-based routing.** Tag `customer-impact` and have Cyrus jump on it the moment the issue is filed. * **Inbound integrations.** Issues filed by Zapier, Slack workflows, or other automation can be auto-routed to Cyrus by including a label in the request. ### Mention Cyrus in a comment Mention `@Cyrus` in any Linear comment to give ad-hoc instructions on a ticket, even on tickets that aren't assigned to the agent. Use this to: * Kick off work on a ticket that's currently assigned to a human * Ask follow-up questions in an existing agent thread * Provide feedback after a PR is opened ("address the review comments and re-push") Cyrus replies in the same thread, so the conversation stays attached to the ticket. *** ## Configuration Linear-related behavior is configured under [Settings → Behaviours](https://app.atcyrus.com/settings/behaviours) in the dashboard. ### Auto-assign by label Pick the Linear labels that should automatically delegate new issues to Cyrus. Click **Configure Labels**, tick any labels from your workspace, and save. See [Create an Issue With an Auto-assign Label](#create-an-issue-with-an-auto-assign-label) for the full behavior. If no labels are configured, Cyrus only works on issues that are manually assigned (or where someone @mentions the agent). ### Issue update trigger When enabled, Cyrus receives a webhook every time an issue's title, description, or attachments change during an active session, and decides whether the change affects its current plan. Useful when you frequently edit the issue after Cyrus has already started. Requires `cyrus-ai` v0.2.19 or higher on self-hosted runtimes. ### Repository routing How Cyrus picks *which* repository to open an issue against is controlled by routing labels, projects, teams, and description tags. That's covered separately in [Labels and Routing](/labels-and-routing). *** ## Working with Cyrus in Linear Every Cyrus session has a dedicated comment thread on the Linear issue. * **Live activity feed.** Tool calls, file edits, and reasoning appear in the thread as the agent works. * **Status sync.** Cyrus moves the issue through Linear states as it progresses (typically `Todo` → `In Progress` → `In Review`). * **Bidirectional comments.** Reply in the thread to give feedback or change direction; Cyrus reads your reply and continues the session. * **PR and session links.** When a pull request opens, Cyrus posts the link to the thread. A "View session" link is attached to the issue for deeper inspection. * **Sub-issues.** For orchestrator-style workflows, Cyrus creates sub-issues to coordinate large work. Each one becomes its own session. See [Labels and Routing](/labels-and-routing#coordinate-large-or-multi-part-work). *** ## How it works Under the hood the integration uses Linear's OAuth 2.0 and webhook APIs: | Component | Description | | ------------------ | ----------------------------------------------------------------------------------------- | | **OAuth** | Workspace tokens are encrypted at rest and refreshed automatically | | **Webhooks** | Issue, comment, label, and status events are delivered to Cyrus and verified by signature | | **Agent sessions** | Each trigger opens an isolated session tied to the originating issue | | **Status sync** | State transitions are written back through Linear's API as work progresses | *** ## FAQ **Can I connect more than one Linear workspace?** Yes, through additional Cyrus workspaces. Each Cyrus workspace is connected to exactly one Linear workspace, but a single Cyrus account can own multiple workspaces. To add another, click the workspace name in the top-left (just below the Cyrus logo) and pick **Add new workspace** from the dropdown. That starts a new subscription and onboarding flow for the new workspace. Once it's set up, you can switch between workspaces from the same dropdown without signing out. **Cyrus didn't pick up my issue. Why?** * Confirm the issue's team is selected under **Settings → Linear → Teams**. * Verify the issue is assigned to the Cyrus user, was created with a configured auto-assign label, or includes an `@Cyrus` mention. * Check that your team has an active subscription. * See [Troubleshooting](/troubleshooting) for more. **Cyrus picked the wrong repository.** Repository routing follows a strict priority order: description tag → routing label → project → team. See [Labels and Routing](/labels-and-routing#routing-priority). **Can Cyrus work on multiple issues at the same time?** Yes. Each issue runs in its own isolated worktree and session. **Can I stop Cyrus mid-session?** Yes. Click the stop button on the agent session in Linear to halt the run immediately. You can also reply in the agent thread asking Cyrus to stop or change direction, or unassign Cyrus from the issue for a hard stop. **What permissions does the OAuth app actually use?** See the [permissions table above](#permissions-cyrus-requests). Cyrus does not need access to private projects or documents outside the teams you selected. **My team uses Linear's native AI agents and Cyrus together. Is that supported?** Yes. Cyrus runs as its own user in your workspace, so it doesn't conflict with other agents. Use assignment or auto-assign labels to disambiguate who handles a given issue. **How do I disconnect Linear?** Go to [Integrations settings](https://app.atcyrus.com/settings/integrations), open the Linear card menu, and choose **Disconnect Linear**. This revokes the token and stops all webhook processing. You can reconnect at any time. *** Get support on Discord