Linear

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

---

​

Setup

Linear is connected during the onboarding wizard, but you can also connect it (or reconnect) from your Integrations settings.

​

Permissions Cyrus Requests

---

​

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)
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 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, 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 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 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 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.

---

​

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.

---

​

How It Works

Under the hood the integration uses Linear’s OAuth 2.0 and webhook APIs:

---

​

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 for more.

Cyrus picked the wrong repository. Repository routing follows a strict priority order: description tag → routing label → project → team. See Labels and Routing. 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. 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, open the Linear card menu, and choose Disconnect Linear. This revokes the token and stops all webhook processing. You can reconnect at any time.

---