How Cyrus Chooses Work

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.

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 or more repositories
4. Cyrus creates a clean worktree for each target repository
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 or More Repositories

By default, Cyrus routes each issue to a single repository. But when you need an issue to fan out across multiple codebases (for example, a feature that touches both a frontend and a backend), Cyrus supports that explicitly. An issue can target multiple repositories when you:

• Add multiple [repo=...] description tags (or use repos=frontendreponame,backendreponame)
• Apply multiple routing labels, each pointing to a different repository

When an issue fans out, Cyrus creates a separate worktree and agent session per target repository. → See Labels and Routing for the full syntax and worked examples.

---

​

Routing Priority

When more than one routing signal is present, Cyrus resolves the target repository (or repositories) in this order:

1. Description tag — [repo=...] or repos=... in the issue description (highest)
2. Routing labels — labels mapped to repositories
3. Project assignment — Linear project mapped to a repository
4. Team selection — the issue’s Linear team (lowest)

Higher-priority signals always override lower-priority ones. If no signal matches, the issue is ignored.

---

​

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.