> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Delegation

> Delegate Linear issues to Macroscope — an agent picks up the ticket, works it autonomously, opens a pull request, and streams progress back into the issue.

Delegate a Linear issue to Macroscope and an [agent](/concepts/agents) picks it up: it reads the ticket, works the task on a cloud VM, opens a pull request, and streams its progress back into the issue as an activity timeline. Follow-up comments in Linear reach the running agent, and the agent keeps shepherding the work — CI failures, review comments — until the task lands.

## How it works

1. You delegate an issue to the Macroscope agent in Linear. Linear opens an **agent session** on the issue.
2. Macroscope acknowledges within seconds: *"Picking up this issue — getting started."*
3. The platform matches the issue against your [flights](/concepts/flights). A flight with a matching `linear_delegation` trigger controls how the agent spawns — [workspace](/concepts/workspaces), [persona](/concepts/agent-personas), model, instructions. With no matching flight, the agent spawns directly from the ticket.
4. The agent works the task and posts progress to the session: status updates, pushed commits, the opened pull request, and a final result. The PR and the agent's dashboard page are attached to the session as links.
5. The agent stays reachable. Prompting the session sends a follow-up to the same agent; stopping the session interrupts its current turn.

## Setup

<Steps>
  <Step title="Install the Macroscope GitHub App">
    Your GitHub org is your tenant. If you haven't already, install the app at [app.macroscope.com](https://app.macroscope.com) — see the [admin quickstart](/admin-quickstart).
  </Step>

  <Step title="Connect Linear to Macroscope">
    Connect your Linear workspace to your organization at [app.macroscope.com](https://app.macroscope.com). This installs the Macroscope agent in Linear and links the Linear workspace to your GitHub org, so delegations route to your tenant.
  </Step>

  <Step title="Create a service profile">
    Delegated agents are machine agents — they run under a [service profile](/concepts/service-profiles), not a personal account. By default, delegations use a service profile accessible to **all users** in your organization; create one under Organization Settings → Service Profiles on the [dashboard](/guides/dashboard). A [flight](#customizing-delegations-with-flights) can set its own `service_profile` instead, so if every delegation is routed through flights, the shared profile is not needed. Without either, delegations fail with an actionable error in the Linear session.
  </Step>
</Steps>

<Note>
  Linear delegation is enabled per organization. If a delegation responds with *"This feature is currently disabled"*, contact the Macroscope team to enable it for your org.
</Note>

## Delegating an issue

In Linear, delegate the issue to the **Macroscope** agent — assign the issue to the agent, or delegate it from the issue's menu. Linear creates an agent session on the issue, and everything the agent does shows up there.

What you'll see in the session:

* **Acknowledgement** — *"Picking up this issue — getting started."* within seconds.
* **An autopilot note** — the agent runs in autopilot: after the initial work lands (e.g. a PR is opened), it keeps monitoring CI failures, review comments, and base-branch conflicts, and continues shepherding the task automatically. Every update includes a link to the task's Murmur settings where you can toggle autopilot features off.
* **Progress activity** — status updates as the agent works, pushed commits, and an *"Opened pull request"* action linking the PR.
* **Links on the session** — the agent's Murmur dashboard page and the pull request, attached as external links.
* **A final result** — a completion response, or an error explaining what went wrong.

The agent's task description is the ticket itself: the issue's title, description, and comment context as Linear provides them.

### Where the agent runs

The spawned agent gets a stable identity derived from the issue — `ENG-123` becomes agent `linear-eng-123` — and is tagged `linear-<your-name>` so you can filter your delegations on the [dashboard](/guides/dashboard). The dashboard link in the session pre-selects that filter.

Which [workspace](/concepts/workspaces) the agent uses:

* **A flight matched** — the agent runs in the flight's workspace, with the flight's persona, model, and instructions. See [Customizing delegations with Flights](#customizing-delegations-with-flights).
* **No flight matched** — the platform selects a workspace (and persona) automatically, weighing the ticket's full metadata: team, project, labels, priority, and description. If your org has a single workspace, it's used directly.

<Tip>
  Automatic selection is a reasonable default, but flights make routing explicit and repeatable. If delegations should land in a specific workspace with specific instructions, define a flight.
</Tip>

## Follow-ups, stop, and revival

The delegated agent sleeps when idle instead of terminating, so the Linear session stays live for its whole life:

* **Prompt the session** — your message is queued as a follow-up to the same agent, with its full conversation context. Use this to answer questions, redirect the work, or request changes.
* **Stop the session** — interrupts the agent's current turn. The agent stays alive and reachable; prompt it again to continue.
* **Revival** — if the agent has since been torn down, prompting the session revives it in place with its full conversation history. Same agent, same session — the follow-up is never dropped.

## Customizing delegations with Flights

A [flight](/concepts/flights) is a Markdown document in your catalog that defines how agents spawn: which workspace they run in, what persona and model they use, what instructions they follow, and — for multi-agent flights — a DAG of agent tasks a pilot orchestrates. Adding a `linear_delegation` trigger to a flight routes matching delegations through it.

```markdown theme={null}
---
workspace: backend
service_profile: linear-bot
persona: programmer
out: pr
on:
  linear_delegation:
    team: ENG
---

# Backend Ticket Handler

Work the delegated issue. Follow the team's coding conventions in
CONTRIBUTING.md, keep the change minimal, and open a pull request that
references the ticket identifier in its description.
```

```bash theme={null}
murmur set flight backend-tickets < backend-tickets.md
```

With this flight in place, every issue delegated from the `ENG` team spawns a `programmer` agent in the `backend` workspace, with the flight's prose appended to the ticket context as standing instructions.

### Matching rules

The `linear_delegation` trigger supports three optional filters, matched against the delegated issue:

| Filter    | Matches                                                         | Value               |
| --------- | --------------------------------------------------------------- | ------------------- |
| `team`    | The issue's team key (e.g. `ENG` for issue `ENG-123`)           | Single value        |
| `labels`  | The issue's label names — **all** listed labels must be present | List of one or more |
| `project` | The issue's project name                                        | Single value        |

All filters on a trigger must match (AND semantics). A trigger with no filters is a catch-all that matches every delegation. Unlike GitHub event triggers, `linear_delegation` triggers take no `repos` list — routing is by ticket attributes, not repository.

When several flights match the same delegation, the highest `priority` (a frontmatter field, default `0`) wins. Two flights at the same priority with overlapping triggers are rejected when you write them, so the winner is always unambiguous. A common pattern is team-specific flights at `priority: 10` plus a filterless catch-all at `priority: 0`:

```yaml theme={null}
# team flight
on:
  linear_delegation:
    team: ENG
priority: 10
```

```yaml theme={null}
# catch-all flight
on:
  linear_delegation: {}
```

If no flight matches, the delegation falls back to the default behavior: automatic workspace and persona selection from the ticket metadata.

### What a flight controls

| Flight field      | Effect on the delegated agent                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `workspace`       | The [workspace](/concepts/workspaces) — repos, environment, image — the agent runs in                            |
| `persona`         | The [agent persona](/concepts/agent-personas) (zero-agent flights)                                               |
| `model`           | Model override (e.g. `claude-opus-4-8`)                                                                          |
| `out`             | Expected output: `pr` (default for delegations), `push`, `respond`, or freeform                                  |
| `service_profile` | The [service profile](/concepts/service-profiles) the agent spawns under, instead of the org-wide shared profile |
| `tags`            | Extra dashboard [tags](/catalog/tag), alongside the automatic `flight-<name>` and `linear-<delegator>` tags      |
| Body prose        | Standing instructions appended to the ticket context                                                             |

The agent's prompt is assembled as: the ticket's routing facts (team, labels, project), then the ticket content (title, description, comments), then the flight's body. So the flight's prose reads as instructions *about* the ticket, and the agent always sees both.

### Multi-agent flights

A flight with H2 agent sections runs as a **pilot**: the delegated agent reads the flight's DAG and orchestrates sub-agents through it — dependencies, gates, fanout — exactly as described in [multi-agent orchestration](/guides/multi-agent-orchestration). The pilot is the agent bound to the Linear session, so progress and follow-ups flow through it.

```markdown theme={null}
---
workspace: backend
service_profile: linear-bot
on:
  linear_delegation:
    labels: [needs-design]
---

# Design-First Ticket Handler

## design

> persona: architect
> out: respond

Analyze the delegated issue. Produce a design: affected components,
approach, and edge cases.

## implement

> persona: programmer
> needs: design
> out: pr
> gate: ci

Implement the design. Open a pull request and get CI green.
```

Unlike GitHub-triggered flights — which terminate when idle — a flight spawned from a Linear delegation sleeps when idle, so prompting the ticket always reaches the pilot.

## Troubleshooting

| Message in the Linear session                                                            | Meaning                                                                                        | Fix                                                                                                 |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| *"This feature is currently disabled. Please contact the Macroscope team to enable it."* | Linear delegation is not enabled for your organization.                                        | Contact the Macroscope team.                                                                        |
| *"No service profile available. Create a service profile accessible to all users…"*      | Delegated agents need a service profile as their principal, and none is open to all org users. | Create one under Organization Settings → Service Profiles, or set `service_profile` on your flight. |
| No response at all                                                                       | The Linear workspace isn't connected to your Macroscope organization.                          | Connect Linear at [app.macroscope.com](https://app.macroscope.com).                                 |

***

| Type      | Page                                                           |
| --------- | -------------------------------------------------------------- |
| Concept   | [Flights](/concepts/flights)                                   |
| Reference | [flight](/catalog/flight)                                      |
| Guide     | [Multi-agent orchestration](/guides/multi-agent-orchestration) |
| Concept   | [Agents](/concepts/agents)                                     |
| Concept   | [Agent Personas](/concepts/agent-personas)                     |
| Concept   | [Workspaces](/concepts/workspaces)                             |
| Concept   | [Service profiles](/concepts/service-profiles)                 |