Automations

An automation is a small rule that lives in one channel: when something happens, the channel acts. The channel's agent posts the reply or reaction, and anything that would cost money — an agent actually doing work — waits for a person to approve it first.

Automations run within about a minute of their trigger.

Build one

1. Open the channel menu (the channel's name in the header) and choose Automations.
2. New automation — name it, pick a trigger, add what happens.
3. Save. The rule is live; the toggle on the list turns it off any time.

Creating and editing automations is for workspace admins. Everyone in the channel can open the list and see what's automated and when it last ran.

The same controls are available to a personal coding connection. Use list_automations, save_automation, set_automation_enabled, and delete_automation over MCP, or the matching /api/v1/channels/:id/automations REST endpoints. Each connection stays inside the workspace it was created for, and a channel's definitions and run history follow that channel's visibility.

Triggers

• A message matches — a substring to look for, optionally only messages with a file attached. The automation never reacts to its own output, so two automations can't chase each other.
• On a schedule — every N minutes (15 at the least). A re-enabled or newly created schedule waits for its next boundary; it never replays what it missed.
• A PR merges / Checks fail on a PR — from the channel's linked repo, at the moment GitHub reports it. Checks fire on genuine failures only, once per commit, however many webhook events GitHub sends.
• A task completes — when a task pinned to this channel is set to done, from any direction: the tracker, an agent, or a PR merging. Once per task, ever — reopening and re-completing stays quiet.
• A run finishes — an agent's run in this channel reaches its end, however it ended: a PR ready for review, finished clean, failed, timed out, or canceled. Once per run, ever — a run that ships a PR fires at the review gate, not again when the PR merges. {{text}} carries the run's own line ("Forge's run finished — awaiting review, https://github.com/…/pull/812").
• A webhook calls — anything that can POST fires it. Saving gives you a URL and a key, shown once; send {"text": "…"} and {{text}} carries it. Calls are rate-limited, and a repeated x-delivery-id never fires twice.

What happens

• Reply — a templated message. {{author}}, {{text}}, and {{channel}} fill in from the trigger; on repo events {{text}} carries the event itself ("Checks failed on PR #41 → lint"). Optionally reply in the triggering message's thread.
• React — an emoji on the triggering message.
• Ask an agent — the differentiator. The automation files a task with your prompt and proposes dispatching it to the agent you chose. The proposal appears in the channel as the usual routing card; the agent only starts when someone approves it there. An automation can ask — it can never spend.

So "when checks fail, ask Forge to investigate" means: CI fails, a task is filed with the failure details, Forge is proposed, and the run starts the moment a person approves — with the same report card and review gate as any other agent run.

Run history

Each automation keeps its recent runs — every step, whether it ran, and why it didn't ("no agent member to act as", "no message to react to"). Open the automation to see them.