--- fences) and a body containing the agent task graph, then pipe it to murmur set flight. The server parses the content into structured fields on write.
Content format
The full flight document is a single Markdown file:- YAML frontmatter (between
---fences) declares workspace binding, event triggers, concurrency limits, and root agent configuration. - H1 heading names the flight.
- Prose between H1 and the first H2 provides pilot-level notes — instructions that apply to the entire flight.
- H2 headings define individual agent tasks. Each agent’s body is its prompt. Blockquote lines (
> key: value) set agent metadata.
persona and model fields.
Frontmatter fields
Agent metadata directives
Each H2 agent section supports blockquote metadata lines (> key: value):
Triggers
Theon: block declares event triggers. Each trigger names an event type, a list of repos (as clone URLs), and optional filters.
Trigger repos must be clone URLs that exist in the flight’s workspace. The server validates this at write time.
A
linear_delegation trigger fires when a Linear issue is delegated to the Macroscope agent. Its filters match the issue’s attributes: team (single value, the issue’s team key, e.g. ENG), labels (one or more label names — all must be present on the issue), and project (single value, the project name). All filters must match; a filterless trigger is a catch-all. See the Linear delegation guide.
Priority
When an event matches more than one flight, the highest-priority match wins and lower-priority matches are suppressed. 0 is the default (lowest) priority, so a flight at priority: 100 beats one left at 0. This normally resolves to exactly one flight. The exception is a task_delegation request spanning several repositories: flights whose repos: lists are disjoint may share a priority, so one request can match several at once — dispatch then fails with FAILED_PRECONDITION rather than choosing arbitrarily, and you disambiguate by giving them distinct priorities or narrowing their repos: lists.
Tenant flights take precedence over built-in murmur-* flights before priority is considered: if any of your own flights match an event, the built-ins are shadowed and never run — so you can override a built-in default just by writing a flight that matches the same event, at any priority. Priority then orders the surviving flights within their class; it never arbitrates across the tenant/built-in boundary, so a tenant flight at priority: 0 still beats a matching built-in at priority: 100.
To keep that ordering unambiguous, two of your flights may not share a priority if their triggers overlap — i.e. some single event could match both; the server rejects such a write. Overlap with a built-in murmur-* flight is exempt from this check, since your flight always shadows the built-in. For repo-scoped event types, two triggers overlap when they share an event type, their repos overlap, and their filters are jointly satisfiable; repo-less event types (such as linear_delegation) are compared by their filters instead. task_delegation is an exception: its optional repos: list participates in overlap, with repos: [] matching every repository and non-empty lists overlapping only when their canonical repositories intersect (so two task_delegation flights listing disjoint repos may share a priority). A filter can make two same-priority flights disjoint only for a small set of keys the server treats as single-valued — among the events here, branch and check — and only when the flights require different values for that key: a ci_failure flight on branch: main and another on branch: dev never match the same event, so they may share a priority. Every other filter is treated as multi-valued for this check, so differing values do not disjoin. labels is genuinely multi-valued (one PR can carry both, so labels: [bug] and labels: [feature] overlap); and a linear_delegation team, though each issue has exactly one, is not in the disjoining set either — so team: ENG and team: OPS are treated as overlapping and cannot share a priority (give them distinct priorities instead). schedule (cron) triggers fire on their own timer rather than via event dispatch, so priority does not arbitrate them and they never overlap.
Proto fields
These fields appear on the storedCatalogFlight resource. When you author via markdown content, the server populates them from the parsed frontmatter and body.
You can write a flight either by piping markdown content (with frontmatter) or by setting structured fields directly. When structured fields are present, they are the source of truth and any
content in the request is ignored — the server re-renders content from the structured fields on every write. Provide content alone (no structured fields) to author the flight as markdown.Examples
Event-triggered flight with multiple agents
Issue-labeled flight
Fires when a matching label is added to an existing issue — label an issuemurmur to hand it to an agent:
Zero-agent scheduled flight
CI failure flight
Linear delegation flight
Fanout flight
Listing flights
Reading a single flight
Errors
Related
- Flights — concept overview
- Multi-agent orchestration — guide for building and running flights
- Linear delegation — routing delegated Linear issues through flights
- Workspaces — the resource a flight belongs to
- Agent personas — personas referenced in flight agent sections
murmur set— CLI command for creating and updating catalog resourcesmurmur get— CLI command for reading catalog resources