Events¶

An event is something that happened: an agent finished, a branch moved, the Mac woke up. The app records each one. This page lists them all.

The same names work in three places:

• an agent's wait_for_event tool, to be started again when one happens, or when its time limit of 1 minute to 24 hours runs out, which every wait has (see Have an agent wait for something),
• a workflow's on:, to start an agent when one happens (see Workflow triggers and actions),
• the Events page, where you read what happened.

Names and filters¶

A name is a subject, a dot, and what happened: branch.moved. A subject followed by .*, such as agent.*, matches every event of that subject.

Each event is described the way an MCP server describes its own (events/list): a name, a description, an inputSchema and a payloadSchema, both JSON Schema. The tables below give them as two columns:

• Details are the payloadSchema: what the event carries, shown on the Events page, in a woken agent's message and in a workflow agent's prompt. Every detail is text; one with fixed values, such as outcome, reason, by, how or level, lists them as an enum. An event about an agent also carries agent_title, its title, beside agent, its id, and a woken agent is told both under those names.
• Filter by is the inputSchema: what a wait's where or the keys under a trigger can narrow the event by. Only a few events take any:
• branch on branch.moved, for example branch: agents/fix-640 for one branch. It is raised only for a branch an agent works on, never the default branch (#702), and a wait on the default branch is refused: wait for the ci server's pr.merged instead;
• why on person.away and person.back: locked or idle;
• an MCP server's event's own, which the server checks (see Events from MCP servers).

Nothing else narrows an event: not agent, labels, outcome or any other detail of an agent event, nor a drop box arrival's, a lease's, the disk's, a cost's or a server's.

• A list means any of them. branch: [main, develop] matches either. A list of one is the same as the value on its own.
• Filters are checked against the inputSchema by the same checker as an MCP server's event's, so the sentences read alike. Any other key is an error naming what the event takes: branch.moved takes branch; "to" is not one of its arguments. For an agent event it says how to wait for particular agents instead: agent.finished takes no arguments; "outcome" is not one of its arguments. To wait for particular agents, use wait_for_event with agents. A workflow file with one is unreadable, and says so, rather than firing for every event of its kind.
• A wrong value is an error too: person.away: why is one of locked, idle, not asleep. branch takes any value.
• A wait already waiting when this changed keeps matching as it was written.

The one list¶

wait_for_event with action list gives every event an agent can wait on, in one list: the app's, then each of the project's MCP servers' that it offers by poll. Each is one line of JSON with its name, source (app, or the server's name in mcp.json), description, inputSchema and payloadSchema. A server that could not be asked is named on a line of its own. The workflow tool's description carries the app's part of the same list.

Serving the app's own events over events/poll from the app's MCP endpoint, so any MCP client could subscribe to them, would be possible in this shape; it is not done.

An agent can wait for its own project's events and for this Mac's. It cannot wait for another project's events.

Agents¶

All are about agents in the same project. None takes a filter: to wait for particular agents, use wait_for_event with agents. Each shows:

• agent, the agent's id;
• labels, the agent's labels;
• runtime, its runtime: claude, codex, gemini, grok and the others this version knows;
• started_by: person (you, on the Mac, the phone or the web page), workflow (a workflow started it or resumes it), or agent (another agent started it as its helper).

These describe the agent as it was when the event happened. A label added later doesn't change an event already on the log.

Projects¶

An agent asking for permission is not working, so it does not hold project.idle back: it is counted under waiting_on_you. The agent a workflow on project.idle (or project.*) runs, and any helper it starts, is not counted as work, so the clean-up finishing does not raise project.idle again. A busy period is kept in memory: a restart of the app starts counting again from the next agent that works.

Workflows¶

Branches¶

Drop box¶

Each project has a drop box, the folder .agents/dropbox/ in it. See Hand files to a workflow.

This Mac¶

These belong to the machine the host runs on, not to a project. Any agent can wait for them.

mac.sleep, mac.wake, person.away and person.back are raised only on a Mac: a Linux server has nothing that hears them. On a server, a wait_for_event naming only these is refused, one naming them with others says so in its answer, and manage_workflows says so when it writes or lists a workflow that triggers on them. The disk events fire on both, so they are machine..

No custom events¶

Agents do not raise events of their own. The publish_event tool and the custom. events it raised were removed (#639). A wait on a custom. name is refused, saying why, and a workflow whose on: names one does not run: its page says what is wrong. To wait for another agent, use wait_for_event with agents. A custom. event already on the log still shows, with the agent that published it.

Events from MCP servers¶

An MCP server can offer events of its own, such as checks.failed or pr.merged. The app asks for them the way the MCP events draft (experimental-ext-triggers-events) describes, in poll mode, and only for servers whose initialize declares the events capability. See Start a workflow from an MCP event.

• Names. A server's event is noun.verbed, lowercase, with no prefix, the same shape as the app's own. A name in the app's catalogue is always the app's. A server's event whose noun is one of the app's subjects (agent, project, workflow, branch, lease, mac, machine, person, cost, server, custom) is refused, so a server can never pose as the app.
• Which servers. The servers a project's agents get: the project's .agents/mcp.json once approved, your ~/.agents/mcp.json, and plugins. A trigger without server: hears every one that offers the name; server: narrows it. A local (stdio) server is run by the app, as its own copy, to ask for events.
• Filters are the server's. The keys under a trigger are sent to the server as the subscription's arguments, checked against the event's own filter schema. A list is a list argument, not "any of".
• Asked for while something listens. Only for workflows that are on, not archived, approved, and run on this Mac or server, and for agents' open waits. Two workflows, or a workflow and a wait, with the same server, event and filters share one subscription. It ends when the last of them goes.
• Pace. As often as the server asks, but never more than every 10 seconds, and at least every 5 minutes; every 30 seconds when it doesn't say. Each subscription is asked on its own, so a slow server never holds another up.
• Once each. Each event is recorded once, by the server's event id, and runs each workflow that heard it once, across restarts. The app keeps where each subscription has got to in mcp-events.json in its own folder.
• Starts from now. A new subscription, or one whose filters changed, skips events from before it.
• Missed events. When the app was away longer than the server keeps events, the trigger's line says Events may have been missed since …, and the next event carries a missed_since detail. The events it did get still run.
• Data is data. The event's data is passed to the agent after the workflow's prompt, in a fenced block, marked as coming from the server and not from you. Data over 256 KB is cut, and the event says so.
• Push and webhook delivery are not taken yet. An event offered only that way is shown as not supported.

A server's event carries:

A wait on a server's event, such as checks.failed or checks.*, is a subscription, as a trigger is:

• Checked when it is made. The name is checked against what the project's servers offer (events/list). If none offers it, the wait is refused, saying what each one does offer: No server here offers pr.merge. ci offers checks.failed, pr.merged.
• where is the server's. Its keys are the subscription's arguments, sent to the server and checked against the event's filter schema, as a trigger's are: ci's pr.merged takes branch, pr, repo; "sha" is not one of its arguments. They are not matched against the event's details. server: narrows it to the servers named.
• It subscribes for as long as it waits, from now, sharing a workflow's subscription when they ask for the same thing. When it is answered, times out or is cancelled, the subscription ends unless a workflow or another wait still holds it. A restart keeps it.
• A server that can't be reached, or isn't approved yet, is a warning, not a refusal: the wait subscribes once the server can be asked.

The wait's answer and its line under Waiting now say which servers it subscribed to: Waiting for pr.merged on ci (repo alexec/Agents).

Each workflow page shows a line for each server its event triggers hear, on the Mac, the iPhone and iPad and the web page: when it was last asked and when the last event came, or why not (Can't reach ci, the server no longer offers the event, refused it, or doesn't take the filters).

The Events page¶

On the Mac, Events is a row at the foot of the sidebar, above Resources and Spending. It shows every event, newest first, grouped by day.

• Filters: a menu for all projects, this Mac or one project, and a capsule for each subject: Agents, Workflows, Branches, Drop box and This Mac.
• Each row shows the time, what happened, and the event's name. Under it, what it led to: Woke an agent, Fired a workflow, Refused by a workflow with the reason, or Could not wake an agent with the reason. A repeat shows a count, such as ×4.
• Click a row to see every detail it carries. Copy as trigger copies it as a workflow's on: line, narrowed by the event's filters only: branch on a branch.moved, why on a person.away or person.back. Every other event is copied as its name alone.
• Waiting now, at the top, lists every agent that is waiting for an event, what for and until when, with ✕ to end the wait. It is not shown when nobody is waiting.

On the iPhone and iPad, Events is a row under the project list. It shows the same rows and details, filtered by one menu. It has no subject capsules, no Copy as trigger and no Waiting now.

See also¶

• Have an agent wait for something
• Hand files to a workflow
• Set up a workflow
• Workflow triggers and actions
• Tools the app gives agents
• Statuses and groups