Get "PHP 8 in a Nutshell" (Now with PHP 8.5)
Amit Merchant
Amit Merchant

A blog on PHP, JavaScript, and more

Let the Pull Request Wake Your Agent Up

An AI coding agent can create a pull request, push commits, and even respond to review feedback. But what happens after it has opened a pull request and is waiting for someone to review it?

The usual approach is to keep checking GitHub at regular intervals to see whether anything has changed. The agent might check every few seconds or every few minutes, even when there’s nothing new to report.

This is called polling, and while it gets the job done, it isn’t necessarily the most efficient way to handle something that could be delivered as an event.

GitHub has now introduced something called Event Streams, which gives agents and integrations a way to subscribe to pull request changes and receive updates as they happen.

Instead of repeatedly asking GitHub whether something has changed, an agent can simply wait for GitHub to notify it.

What are GitHub Event Streams?

GitHub Event Streams is a mechanism that allows applications to subscribe to changes happening on a particular pull request.

For instance, an agent could subscribe to events such as:

  • A new review being submitted.
  • New commits being pushed to a pull request.
  • A merge conflict appearing.
  • A pull request being merged or closed.
  • A CI check suite completing.

Once subscribed, GitHub sends these events over a Server-Sent Events (SSE) connection.

This is an important distinction from webhooks. With webhooks, GitHub needs an endpoint on your application where it can send HTTP requests. Event Streams works the other way around: your application opens a connection to GitHub and listens for incoming events.

That means even an agent running on your local machine can receive updates without having to expose a public endpoint.

Of course, this isn’t limited to local agents. Any application that can maintain an authenticated SSE connection can consume these events.

Listening for pull request events

The easiest way to try this is through GitHub CLI.

GitHub CLI 2.105.0 introduced a new command called gh event listen, which lets you subscribe to events on a pull request without having to manually create a subscription and manage the SSE connection yourself.

For example, suppose an agent has opened a pull request and is waiting for someone to review it. You can listen for the next submitted review like so:

gh event listen \
  --resource https://github.com/OWNER/REPO/pull/123 \
  --event com.github.pull_request.review.submitted.v1 \
  --timeout 30m

This command creates a subscription for the specified pull request and waits for a review event for up to 30 minutes.

When someone submits a review, the command prints the event as a JSON object.

You can also listen for other events. For instance, to know when a CI check suite finishes:

gh event listen \
  --resource https://github.com/OWNER/REPO/pull/123 \
  --event com.github.pull_request.check_suite.status.changed.v1 \
  --jq .data.conclusion

This prints the check suite’s conclusion, such as success or failure.

By default, gh event listen exits after receiving the first event. If you want it to continue listening, you can use the --follow flag. You can also use --count to wait for a specific number of events.

One thing to note is that Event Streams is currently in public preview and requires access through GitHub’s waitlist. You’ll also need a supported GitHub authentication token with permission to read the pull request.

Giving AI agents an event-driven workflow

This is where I think Event Streams gets particularly interesting.

Consider an agent that has been asked to implement a feature and open a pull request.

Once the pull request is created, the agent could wait for a review event instead of repeatedly checking GitHub.

When the event arrives, it can fetch the corresponding review using the API URL included in the event, inspect the feedback, and decide what to do next.

For example, if the reviewer requests changes, the agent could examine the comments, update the implementation, push another commit, and continue waiting for feedback.

The same idea can be applied to CI checks. An agent could wait for a check suite to complete and investigate a failure when it happens.

The workflow could look something like this:

  1. Agent creates a pull request.
  2. Agent subscribes to review and CI events.
  3. GitHub sends an event when a review is submitted or a check suite completes.
  4. Agent fetches the latest information and decides what action to take.
  5. Agent continues working or waits for the next event.

This removes the need for a polling loop that keeps asking GitHub for updates when there is nothing new.

It also means the same workflow can run locally or on a remote machine. The important requirement is simply that the agent can maintain the connection to GitHub.

An example listener with Codex

Since I use Codex extensively, let’s see how we can use this workflow with Codex.

Suppose we’ve asked Codex to implement a feature and open a pull request. Once the PR is created, we can have a listener wait for a review event using GitHub Event Streams.

When a review is submitted, the listener queues a message for an existing Codex session. Codex can then fetch the review, inspect the feedback, and act accordingly.

We can put this together using a small Bash script:

#!/bin/bash

PR_URL="https://github.com/OWNER/REPO/pull/123"
CODEX_THREAD_ID="your-codex-thread-id"

while true; do
    REVIEW_API_URL=$(gh event listen \
        --resource "$PR_URL" \
        --event com.github.pull_request.review.submitted.v1 \
        --timeout 30m \
        --jq '.data.api_url')

    if [ -n "$REVIEW_API_URL" ]; then
        codex queue \
            --thread "$CODEX_THREAD_ID" \
            --message "A new review was submitted. Fetch and inspect this review: $REVIEW_API_URL. Address actionable feedback." \
            --resume
    fi
done

As you can see, Codex CLI’s codex queue command makes this particularly useful. We don’t necessarily need to start a completely new Codex run every time an event arrives. We can send a follow-up message to an existing session and preserve its conversation context.

One thing to keep in mind is that Event Streams doesn’t replay events that occurred while the listener was disconnected. So, in a production implementation, we’d also want to handle reconnections and check the current PR state when the listener starts.

A few things to keep in mind

Event Streams is still in public preview, so there are a few limitations worth knowing about.

First, subscriptions expire after 24 hours. If an agent needs to keep listening beyond that, it must create a new subscription.

Second, events aren’t replayed. If the connection is disconnected when an event occurs, the agent won’t receive that event later. It should fetch the current pull request state after subscribing and whenever it reconnects.

Also, events don’t necessarily contain all the information about what changed. For example, a review event tells you that a review was submitted, but not whether it approved the pull request or requested changes. You need to fetch the latest review using the API URL included in the event.

Events can also arrive more than once or out of order, so an agent shouldn’t blindly act on every event. It should fetch the current state before deciding what to do.

These are fairly important considerations when building something that needs to run reliably rather than just demonstrating a proof of concept.

Wrapping up

I think GitHub Event Streams is a nice addition to the tooling available for building AI-powered development workflows.

We’ve mostly been thinking about what coding agents can do: write code, fix bugs, create pull requests, and respond to instructions. But there’s another part of the problem that doesn’t get as much attention: how agents know when something needs their attention.

Polling is a straightforward way to solve that, but it isn’t always necessary. An event-driven approach gives agents a way to wait for something meaningful to happen and continue working when it does.

And perhaps this is another small step towards making coding agents feel less like tools that we repeatedly prompt and more like participants in an ongoing development workflow.

👋 Hi there! This is Amit, again. I write articles about all things web development. If you enjoy my work (the articles, the open-source projects, my general demeanour... anything really), consider leaving a tip & supporting the site. Your support is incredibly appreciated!

Comments?