Skip to main content
Cyrus doesn’t guess what to work on.
It uses clear signals from Linear, repositories, and labels to decide when to act and where to make changes. This page explains the mental model behind Cyrus so you can predict its behavior with confidence.

​
The High-Level Flow

At a high level, Cyrus works like this:
  1. A Linear issue changes state (assigned, labeled, updated)
  2. Cyrus checks whether that issue matches any configured rules
  3. Cyrus selects one repository
  4. Cyrus creates a clean worktree
  5. Cyrus starts working
If any step doesn’t match, the issue is ignored.

​
Repositories Are Routing Targets

Repositories are not just codebases — they are destinations. Each repository you add tells Cyrus:
“If an issue matches these rules, work here.”
An issue will only be processed if it matches at least one active repository.

​
Linear Teams and Labels Are Signals

Cyrus uses two types of signals from Linear:

​
Linear Teams

  • Define which teams’ issues are eligible
  • One repository can accept issues from multiple teams
  • Issues from other teams are ignored

​
Routing Labels

  • Further narrow down which issues go to which repo
  • Useful when one team owns multiple codebases
  • Example: frontend, backend, infra
Both signals must match for routing to occur.

​
One Issue → One Repository

Cyrus routes each issue to exactly one repository. If multiple repositories match:
  • Cyrus selects the best match based on routing rules
  • Ambiguous routing is avoided by design
Best practice is to make routing rules explicit.

​
What Cyrus Will Ignore

Cyrus will not process issues when:
  • No repository is active
  • The issue’s team isn’t selected
  • Required labels are missing
  • The repository was deleted or disabled
  • Required integrations aren’t connected
If Cyrus appears “idle,” one of these is usually the reason.

​
What’s Next

Now that you understand how routing works, you can control it. fOjhOFI

Cyrus Community

Get tips and tricks for routing on Discord