Workflows, steps, sensors, and a registry.

A workflow is a directory of steps.

Each step is one .md file, and the after: links set the order. Here's the resolve workflow, file by file. Each step runs after the one before it.

---
on:     WorkItem
agent:  Claude
output:
  goal: str
---
Decide the goal for "{{ event.description }}" given
the work item at {{ event.link }}.

---
after:  arbitrate
agent:  Claude
output:
  pr_url: url
  summary: str
---
Implement the goal: {{ arbitrate.goal }}. Open a PR
and summarize the change.

---
after:  fix
agent:  Claude
output:
  verdict: enum[pass, fail]
---
Review {{ fix.pr_url }}: {{ fix.summary }}. Return a
pass/fail verdict.

---
after:  review
agent:  Claude
---
If {{ review.verdict }} is pass, merge the PR and ship
the change.

A step is a markdown file describing a single agent task.

Every step file has two parts. A short header between the --- lines wires the step into the graph. The prose below is the agent's objective.

---
on:     WorkItem        # what triggers the step
agent:  Claude      # who runs it
output: { goal: str }   # typed result
---
Decide the goal given the work item at
{{ event.link }}.

Optional: emits: puts an event on the bus for other workflows.

Outputs and events: two ways to pass a result

A step can hand off its result two ways, and they are different things. An output stays inside the workflow. An event goes out to the rest of the system. The same value almost never wants both, so the question to ask is: does another workflow need this?

Rule of thumb: a within-workflow handoff (arbitrate → fix) is an output. A cross-workflow handoff (triage → resolve via a WorkItem) is an event.

Sensors turn the outside world into events.

A sensor is a small Python function in the sensors/ directory. It listens for a signal (a webhook or a poll) and returns a typed event onto the bus, where a workflow's first step picks it up with on:.

from collections.abc import Iterator

from loopy import sensor
from loopy.events import CustomerTicket, PageChanged


# webhook: Zendesk POSTs a new ticket; you shape it into a CustomerTicket
@sensor(webhook="/hooks/zendesk", emits="CustomerTicket")
def zendesk_tickets(req) -> CustomerTicket:
    ticket = req.json["ticket"]
    return CustomerTicket(ticket_id=ticket["id"], subject=ticket["subject"],
                          body=ticket["description"], link=ticket["url"])


# poll: no feed, no webhook, just a page that changes when it changes.
# one tick can yield many events; snapshots is your own store
@sensor(poll="12h", emits="PageChanged")
def page_watch(req) -> Iterator[PageChanged]:
    for url in ("https://vendor.example.com/changelog",
                "https://cloud.example.com/deprecations"):
        old, new = snapshots.swap(url, fetch(url))
        if old and old != new:
            yield PageChanged(url=url, summary_of_change=diff_summary(old, new))

Sensors can live in any .py file under sensors/, so organize them however you like. Loopy scans the whole directory; the file name does not matter. init just puts them in sensors/sensors.py to start. Each sensor is a top-level function marked with @sensor.

What a poll interval means

A poll interval is a plain duration: a whole number followed by a unit, no space. The units are s (seconds), m (minutes), h (hours), and d (days), so "30s", "5m", "1h", and "2d" are all valid. It's a duration, not a cron expression. If you need to run on a clock (every day at 9am), put cron("0 9 * * *") in a workflow's on: instead. A malformed interval is caught when you compile.

Common GitHub events are built in

You don't write a sensor for the usual GitHub triggers. A workflow names a built-in event in on: directly, and Loopy registers its contract and the /hooks/github sensor for you. No sensors/ file, no registry.yml entry.

---
on:    Github.PullRequestOpened
agent: Claude
---
Review PR #{{ event.number }} on {{ event.repo }}.

The built-in events are Github.PullRequestOpened, Github.PullRequestMerged, Github.IssueOpened, Github.IssueCommentCreated, and Github.Push. They fire for any repository your GitHub App delivers. See GitHub in the integrations docs for each event's payload and setup. For a source the built-ins don't cover, write your own @sensor as above.

Key abstractions live in YAML.

One file declares the reusable pieces your steps refer to by name: the agents that run steps, the sandboxes their code runs in, and the events that move between workflows.

agents:                       # define one per harness, then reference any by name from a step
  Claude:                 # driven by Claude Code
    sandbox: BaseSandbox
    model:   claude-opus-4-8
    harness: claude-code
    skills:  [code-review, testing]

  Codex:                  # same project, driven by Codex
    sandbox: BaseSandbox
    model:   gpt-5.5
    harness: codex
    skills:  [code-review]

  OpenCode:               # same project, driven by OpenCode
    sandbox: BaseSandbox
    model:   claude-sonnet-4-6
    harness: opencode
    skills:  [code-review]

sandboxes:                    # where an agent's code runs: image + env
  BaseSandbox:
    provider: daytona
    image:    { debian_slim: "3.12", apt: [git], workdir: /home/loopy, user: loopy }
    env_file: secrets/base.env

events:                       # typed messages on the bus; a step may only trigger `on:` one registered here
  Incident: { source: enum[sentry, pagerduty, datadog], issue_id: str, title: str, link: url }
  CustomerTicket: { ticket_id: str, subject: str, body: str, link: url }
  WorkItem: { link: url, description: str }
  PageChanged: { url: url, summary_of_change: str }

Names: one namespace, Capitalized

The three sections (agents:, sandboxes:, events:) are each optional, but their entries share one namespace: a sandbox, an agent, and an event can never share a name. Every name is Capitalized, with one exception: default is the one reserved lowercase name, and you can define it for a sandbox or an agent (it names the one used when none is picked explicitly). No other lowercase names are allowed. The Github. prefix belongs to the built-in GitHub events, so your own events can't use it. All of this is checked when you compile.

Agent keys

An agent is a named configuration (model, harness, sandbox, skills) that a step picks with agent:.

A top-level defaults.agent block fills in any of these for agents that don't set them: model, harness, and sandbox are plain overrides (the agent's own value wins), and an agent's own skills list replaces the default list entirely (no merging). There are no built-in agents: every agent a step names is declared in the registry, so its model and harness pairing is always visible in the file.

Sandbox keys

A sandbox is where an agent's code runs: a provider, an image, and what the box may reach.

Event fields

An event's body is its field map: EventName: { key: type, ... }, with no wrapper key. Fields are optional (an event with none is a bare signal). Each field's type is one of str, int, float, bool, url, or enum[a, b, c], or an inline JSON Schema object when the shorthands don't fit. A step's on: or emits: may only name an event registered here, plus the built-in Github.* events, which come pre-registered.