How to route Linear mentions by team and project

Add one linear.yaml to your .ellipsis repository to pick which agent answers @ellipsis on each Linear team's or project's issues, with its own prompt, repositories, and budget.

@ellipsis at the start of a Linear issue comment always gets an answer: with no configuration, the built-in responder reads the issue and replies. One file makes that answer yours: linear.yaml in your .ellipsis repository names an agent per team or per project, each with its own prompt, repositories, environment, and budget.

Prerequisites: the Linear integration connected and the GitHub App installed, plus a repository named .ellipsis in your organization.

ellipsis:
  version: v1
  kind: linear
  name: Linear agents

environment:
  repositories:
    - name: web-repo
    - name: api-repo

agents:
  - name: billing
    linear:
      projects: [Billing]
    claude:
      system: |
        You answer @ellipsis on issues in the Billing project. The billing
        code lives in api-repo/billing; read it before you answer, and cite
        the exact function that produces the behavior the issue describes.
    budget: 2.00

  - name: engineering
    linear:
      teams: [ENG]
    claude:
      system: |
        You answer @ellipsis on engineering issues. Answer from the code in
        front of you. When asked to fix something, make the change and open
        a pull request linked back to the issue.
    budget: 3.00

  - name: everyone-else
    linear:
      teams: ['*']
    permissions:
      github:
        permissions: read_only
    budget: 1.00

Commit that to .ellipsis/linear.yaml and it is live when it merges to that repository's default branch. Issues in the Billing project get the billing agent, the rest of the ENG team's issues get the engineering agent, and every other team gets a read-only responder. A Linear issue has no repository of its own, so the sandbox clones exactly what environment.repositories declares.

Where the file goes, and why only one

linear.yaml is read from your .ellipsis repository only, at one of .ellipsis/linear.yaml, ellipsis/linear.yaml, .agents/linear.yaml, or agents/linear.yaml. A copy in any other repository is ignored: a Linear issue has no repository to scope it, so there is one file for the workspace.

Routing per team and per project

Each agent's linear: block says which issues it answers. Two axes:

teams — team keys (ENG) or team names (Engineering), matched case-insensitively. '*' claims every team, and therefore every issue.
projects — project names, matched case-insensitively. There is no project wildcard; teams: ['*'] already covers every issue.

The most specific rule wins: a named project beats a named team, and a named team beats '*'. Each team and each project may be claimed by exactly one agent, and only one agent may claim '*'; a file that breaks either rule is rejected.

An issue nobody claims still gets an answer: the built-in responder handles it, so @ellipsis never goes silent on a team you forgot to list.

What the agent sees

The issue is the conversation. The first @ellipsis comment starts a durable conversation on that issue and every later leading @ellipsis comment continues it, with the transcript and working tree intact. A 👀 reaction on your comment acknowledges it while the session works. The comment must lead with the mention, so a mirrored GitHub thread never summons Ellipsis twice.

A file-level environment: block or a saved environment name is inherited by every agent, and an agent's own environment: overrides it field by field; an environment named by reference wins whole.

Budgets and spend

Each agent's budget caps a single conversation's cumulative spend across its turns, in USD; omit it and the conversation inherits your account's default session budget. Details in Budgets.

When the file is wrong

Validation is strict and the file is checked on every push to your .ellipsis default branch: an unknown field, a team or project claimed twice, or two '*' agents is a sync error you see in the dashboard. A file that fails to parse keeps the last version that parsed routing until you fix it.

Slack channels and DMs route from slack.yaml: Build a custom Slackbot. GitHub repositories route from github.yaml: Route GitHub mentions.