Triggers
Run an agent in response to GitHub events — PR-opened triggers and @cluster-build mentions.
Triggers
A trigger runs an agent in response to a GitHub event. There are two lanes: the zero-config mention lane and the opt-in auto lane.
Mention lane (zero-config)
Comment on a pull request with a mention and a built-in reviewer runs immediately — no setup, no trigger to create:
@cluster-build review— a standard code review.@cluster-build ultrareview— a deeper, multi-pass review.
Each mention creates a session that reviews the PR and posts back. Mention fires are deduplicated per webhook delivery, so a re-delivered event won't run twice.
Auto lane (your agents)
The auto lane runs your agent whenever a matching GitHub event arrives on a repo. Create a trigger to opt in.
Open an agent's Triggers and add one: choose the repo, the events to fire on, and (optionally, under Advanced) a kickoff template. Triggers can be enabled and disabled in place.
POST /v1/triggers. agent, repo, and events are required.
curl https://agents.clusterbase.dev/v1/triggers \
-H "Authorization: Bearer $CLUSTER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "agt_3f9c2a",
"repo": "acme/web",
"events": ["pull_request.opened"],
"kickoff_template": "Review PR {{pr}} on {{branch}} in {{repo}}."
}'{
"id": "trg_d4e5f6",
"agent_id": "agt_3f9c2a",
"source": "github",
"repo": "acme/web",
"events": ["pull_request.opened"],
"kickoff_template": "Review PR {{pr}} on {{branch}} in {{repo}}.",
"enabled": true
}| Field | Notes |
|---|---|
agent | The agent id to run. Must be one you own. |
repo | A GitHub owner/name slug. |
events | A non-empty subset of the supported events (below). |
kickoff_template | Optional. Omit to use the agent's built-in kickoff. |
Supported events
| Event | Fires when |
|---|---|
pull_request.opened | A pull request is opened. |
pull_request.ready_for_review | A draft PR is marked ready for review. |
Kickoff template placeholders
When a trigger fires, the kickoff template is rendered with values from the event:
| Placeholder | Expands to |
|---|---|
{{repo}} | The source PR repo (owner/name). |
{{pr}} | The pull request number. |
{{branch}} | The PR's head branch. |
{{path}} | The cloned path of the source repo in the VM. |
{{instruction}} | The instruction parsed from the triggering event. |
{{repos}} | Every repo cloned for the run — the source PR repo plus the agent's configured repos. |
Manage a trigger
Update with PATCH /v1/triggers/{id} (set repo, events, enabled, or
kickoff_template), and delete with DELETE /v1/triggers/{id}.
To see what a trigger has done, list its fires — one record per webhook-delivery-to-run:
curl https://agents.clusterbase.dev/v1/triggers/trg_d4e5f6/fires \
-H "Authorization: Bearer $CLUSTER_TOKEN"Each fire reports its status, the session_id it created, and the repo /
pr_number it ran against — open that session to read the event
stream.