Skip to main content
A flight is a Markdown document that defines a directed acyclic graph (DAG) of agent tasks. Each H2 section is an agent with a prompt, dependencies, and optional configuration. A pilot agent reads the flight and orchestrates the sub-agents.

​
Structure

A flight is plain Markdown:
  • H1 — the flight name
  • H2 — each agent’s slug (unique within the flight)
  • Blockquote lines (> key: value) — agent metadata (persona, dependencies, gates)
  • Body text — the agent’s task prompt

​
Dependencies

Two kinds of transitions connect agents: needs — the downstream agent starts after the upstream completes. New branch, new VM, no inherited conversation context. Multiple dependencies are comma-separated — all must complete before the dependent starts. continues — the downstream agent sends a follow-up to the upstream on the same branch and VM. Full conversation context is preserved. This is a 1:1 relationship.
needs and continues are mutually exclusive. An agent can have one or the other, not both.

​
Metadata directives

​
Fanout

The each directive creates a template agent that the pilot expands into one instance per item. The {} placeholder in the prompt is replaced with each item. When another agent needs an each agent, all expanded instances must complete.

​
Gates

Gates block downstream agents until conditions are met — CI checks passing, a review agent approving the PR, human approval, or the PR being merged.

​
Event triggers

Flights stored in the catalog can include YAML frontmatter with on: triggers — issue_opened, issue_labeled, pr_opened, pr_labeled, push, schedule (cron), ci_failure, agent_feedback, and linear_delegation (a Linear issue delegated to the Macroscope agent — see the Linear delegation guide). When a matching event arrives, the platform spawns the flight automatically. When several flights match the same event, the highest-priority flight wins (the priority: frontmatter field — see Priority). See the flight reference for all frontmatter fields and trigger types.

​
Tags

Every agent a flight spawns is automatically tagged with flight-<name> — a flight named deploy tags its agents flight-deploy — so you can group and filter a flight’s runs on the dashboard. Add your own tags with a tags: frontmatter list; they apply to the flight’s agents alongside the automatic tag. Tag names are DNS-label slugs ([a-z0-9][a-z0-9-]{0,62}); the platform creates any that don’t yet exist, and rejects a flight whose name is too long to form a valid flight-<name> tag. See tags.

​
Daemon vs. standard flights

By default, a triggered flight spawns a fresh instance every time it fires. The pilot agent and any sub-agents do their work, then the VM is reclaimed when idle. The next trigger spawns a brand new instance with no inherited state. A daemon flight flips that model. Setting daemon: true in the frontmatter makes the flight a singleton: one persistent pilot agent for the lifetime of the flight. Events arriving while the daemon is running are delivered as follow-ups to the same agent on the same branch and VM, so the daemon can keep state between events. When there’s nothing to process, the agent sleeps instead of terminating, and wakes up when the next event arrives. Reach for a daemon when serial processing matters, or when accumulated context between events is valuable. The merge queue daemon below is a canonical example: it processes one ready-to-merge PR at a time, in order, and sleeps between events instead of spinning up a fresh agent for each one.
If a daemon ever crashes or is killed, the next matching event spawns a fresh instance. Daemons recover on the next trigger, not mid-execution.

​
Running and storing flights

Run a flight with the --flight flag on murmur spawn. Store flights in the catalog with murmur set flight for reuse and event-triggered execution. See the multi-agent orchestration guide for a full walkthrough.