All guides

Running agents on GitHub events

A prompt can start when something happens on GitHub, not at a set time. CI fails on your PR, someone asks for your review, an issue gets your label, a PR merges. SimpleEdit notices, and starts a session with your prompt, with Claude, Codex or OpenCode. Or it starts a whole workflow graph. It works like running agents on a schedule, except the prompt waits for the thing it was written for instead of the clock.

SimpleEdit does the watching itself. It asks GitHub through gh from your computer, so there is no server and no webhook to set up.

A triggered run is a normal session. You can open it, read it and type into it. SimpleEdit itself never posts, approves, labels or merges anything on GitHub. The agent pushes a fix or opens a draft PR only when your prompt asks it to, and everything it did waits in its session for you to read.

Before you start

A prompt in the Prompts section with When set to CI fails on my PR, its filters, the prompt text and Unpause

1. Set up a trigger

  1. Open Prompts in the sidebar and select + New. See Saving prompts for later with Prompts.
  2. Write the prompt. It is sent as the session’s opening message. Use placeholders to point it at the PR or issue that fired.
  3. Open When and pick one of the choices under On GitHub. See the kinds.
  4. After in, pick the repositories to watch. The default is the project’s repository. You can add others that SimpleEdit knows a local folder for. Locate clone… asks for the folder of one it doesn’t know yet.
  5. Fill in the filters. Each has its own row.
  6. Optionally pick A workflow graph under Run, see step 5, or add a Run only if command.

A prompt has either a time or an event, not both.

The When menu open, with the On GitHub group listing the seven events

It acts on what matches now

When a trigger is switched on, it runs for everything that matches at that moment, not only for what happens afterwards. If three of your PRs are red when you switch on CI fails on my PR, it starts on all three, within the caps. Check the filters before you switch it on.

Editing a trigger that is already on does not run it again for a commit or an issue it has handled.

2. The kinds

WhenIt starts whenFilters
CI fails on my PRA check fails on one of your open PRs. It runs once for each commit that fails.Checks: only these check names, blank for any. Drafts too.
Changes asked on my PRSomeone comments on your PR in a way that needs action. Bots and your own comments never count.Only asks for a change. From: only these people.
My review is requestedA PR asks you for a review.Author: only PRs by these people.
A PR is mergedA PR merges into a branch. It watches the project’s repository only.Into: the branch, main by default. Paths: only PRs that change a matching file, such as src/**. Author.
An issue gets a labelAn issue gets the label.Label.
An issue is assigned to meAn issue is assigned to you.Label: only issues with this label.
An issue is openedA new issue is opened. Bots’ issues never count.Label. Author. Members only, on by default: only the repository’s owner, members and collaborators start a run.

Filters that take several names accept a list separated by commas.

Where the session starts

A new session is named ”↻ ‹prompt name› #‹number›“.

3. Once per commit

A trigger for a PR runs once for each head commit. A red head A runs once. A push that makes head B red runs again. Re-running the checks on A does not. Several review comments on one commit make one run.

Issue and merge triggers run once for each issue or PR.

SimpleEdit checks GitHub every 5 minutes while it is open, so a run starts within a few minutes of the event. After your computer wakes, it checks again after a short wait. Something that was true while it slept and still is runs once. Something that came and went in between is missed.

4. Placeholders

Write {pr.url} in the prompt and SimpleEdit fills in the URL of the PR that fired. They are:

Titles, descriptions and comment text are never filled in. Anyone who can open an issue or comment on a PR could write instructions into them, and the prompt would carry those to an agent that runs without you. The session reads them itself with gh, as an agent would for any issue.

For example:

CI failed on {pr.url} (failed checks: {checks.failed}).
Read the failing logs with gh, find the cause, and fix it on this branch.
Run the project's checks before you push. If the failure is not caused by
this change, say so and change nothing.

Other text in braces passes through unchanged. A prompt that uses a placeholder its event doesn’t provide is refused when you save it.

5. Run a workflow graph

By default a trigger starts one plain session. Under Run, pick A workflow graph to start a whole workflow instead. Any repeating prompt can do this, schedules included.

  1. Save the graph as a file in the repository, in the folder the project’s window opened. Type its path under Graph, for example docs/plans/fix-ci.workflow.json. The path stays inside that folder.
  2. SimpleEdit reads the file and shows the graph’s title and task count next to the path.
  3. Unpause the prompt. This arms the graph exactly as you saw it.

Each run creates the workflow from the file and starts a lead session with your prompt. Placeholders in the graph’s briefs and goal are filled in like those in the prompt.

Start it decides whether the workflow starts by itself. It does only when Settings → Workflows → Leads may start workflows is on. Otherwise the workflow waits as a draft, your phone says “workflow waiting for your Start”, and you start it. See Running a Workflow.

If the file changes after you armed it, the next run is skipped and the prompt pauses, with “Graph changed since you armed it”. Read the graph again, then unpause. This also means an agent can’t swap the graph under an armed trigger.

A trigger that runs a workflow graph, with the graph file, its title and task count, and the Start it box

6. Check on it

The status line under the trigger says what it is doing:

Select the ⓘ next to it. It says how often SimpleEdit checks, and Last runs lists each run with its outcome and a link to its session. A run is listed as skipped with the reason: “Gate: ‹reason›”, “Stopped · 3 runs in 24 h”, “Several sessions own #412”, “Graph changed since you armed it”. A run that was due after a sleep ends in “catch-up after sleep”. A run that could not find a local clone started in the project and says so.

The card stays open when you hover it, so you can click the session links.

The status line's ⓘ open, with the rules for this trigger and Last runs listing three runs and one skipped

Run now…

Run now… lists the PRs or issues that match right now. Pick one and it starts with you there. It does not check Run only if. The trigger will not run for that commit or issue again afterwards.

It counts as one of the day’s runs. When nothing matches, the button is not shown.

7. Caps

A trigger can’t loop. Three limits keep it in check:

While a run for the same PR is still going, a new commit waits instead of starting another run. The agent is probably about to push. A run skipped by Run only if and a stopped run start nothing and don’t count.

8. Run only if

A trigger can have a Run only if command, the same one a schedule has. It runs in the project folder before each run, and waits up to 60 seconds. Exit 0 starts the run. Anything else skips it, and the history shows why.

The event reaches the command as environment variables, never in the command text: SIMPLEEDIT_EVENT, SIMPLEEDIT_REPO, SIMPLEEDIT_NUMBER, SIMPLEEDIT_URL, SIMPLEEDIT_HEAD and SIMPLEEDIT_BRANCH. For example, to run only for PRs on a branch prefix:

case "$SIMPLEEDIT_BRANCH" in feat/*) exit 0 ;; *) exit 1 ;; esac

A skipped commit or issue counts as handled, and is not tried again.

9. On your phone

The phone shows the trigger: When, its filters, what it runs and the Run only if command, all read-only. You can Pause and Unpause, and use Run now…. You edit triggers on the desktop.

You get a push when a trigger starts a run while you are away, for example “CI watch · started on ui-pack#412”. The usual push follows when the session finishes its first turn without a question for you.

A trigger on the phone: When, filters, status, Pause and Run now…

10. When an agent adds a trigger

Ask an agent to “add a prompt that fixes my PR when CI fails”. It adds the prompt, with its trigger and graph, and does not switch it on. The prompt lands Paused, marked “added by an agent”. Read the prompt, the trigger, its filters, the graph and the command, then select Unpause. If anything changed since you opened it, the unpause is refused and you read it again.

An agent can add and edit triggers. It can’t arm one, and there is no way for it to start one.

A run that starts a new session while you are away does not wait for you. With Claude, a call that would ask you for permission is denied, and the agent goes on. Open the session to see what it couldn’t do.

Limits

Examples

Each one ends with a session, a pushed fix or a draft PR for you to read. The agent touches GitHub only where the prompt tells it to.

Fix my red CI

When: CI fails on my PR. Leave Drafts too off at first.

CI failed on {pr.url} (failed checks: {checks.failed}).
Read the failing logs with gh, find the cause, and fix it on this branch.
Run the project's checks before you push. If the failure is not caused by
this change, say so and change nothing.

The run goes to the session that owns the PR. A fix that is red again runs once more, and after three runs for the PR, it stops and you take over.

Prepare my reviews

When: My review is requested. Use Author to limit it to people you review often.

{pr.author} asked me to review {pr.url} in {repo}.
Read the PR with gh and prepare me for the review: what it changes,
what looks risky, and what to check first. Don't comment on GitHub.

Keep the docs in step

When: A PR is merged, with Paths set to src/**.

{pr.url} was merged and changes code under src/.
Check whether the docs still match, and if not, open a draft PR that
updates them. If they match, say so and open nothing.