Skip to content

Claude Code plugin

Your pull requests' GitHub Actions results in your open Claude Code session: install, starting the channel, what to watch, every event kind, the options, and what is sent.

Last updated

The runners.io plugin for Claude Code brings your pull requests' CI into your open Claude Code session as it happens. A workflow starts, fails, passes or waits for a deployment approval, or the pull request gets a merge conflict, and Claude is told in the session, so it can read the failed job's log and fix it without being asked to go and look. The plugin's page shows what that looks like; this page is the reference.

It reads your CI from GitHub, with your own GitHub login. It needs no runners.io account and works for any repository that uses GitHub Actions. The channel sends nothing to runners.io; the runners.io MCP server the plugin also installs is contacted when a session starts, as "What is sent" below says. It is open source under the MIT licence, at github.com/runners-io/claude-plugin.

The plugin bundles four things:

  • A CI channel: a small process on your machine that watches your pull requests on GitHub and pushes each change into the session.

  • Tools to choose what to watch, per session: subscribe, unsubscribe, list_subscriptions, ci_status, mute and unmute.

  • A hook that watches a pull request just opened in your session's own repository, by your GitHub login, whether Claude or a script opened it. A pull request in any other repository is never watched without Claude subscribing to it.

  • The runners.io MCP server, for runners.io customers: see the page for the MCP server for GitHub Actions. The channel does not need it.

And four skills: watch-this-pr, fix-failing-ci, setup-github and sign-in.

Channels are a Claude Code research preview, and this channel is in research preview too. It works in the Claude Code terminal app, while the session is open.

  • Claude Code 2.1.80 or later.

  • Node.js 20 or later.

  • The GitHub CLI, gh, signed in to github.com. If you do not have it, the plugin's setup-github skill walks Claude through installing it, with your agreement, and you sign in with ! gh auth login --web --scopes repo.

A private repository needs a gh login with the repo scope.

bash
claude plugin marketplace add runners-io/claude-plugin#v0.3.1
claude plugin install runners-io@runners-io

This installs exactly one release, v0.3.1: the # and the tag pin the marketplace to it, and a release tag is never moved once it is published, so the code you read is the code that runs. To move to a newer release, run claude plugin marketplace remove runners-io (which uninstalls the plugin), then the two commands above with the newer tag. claude plugin list shows the version you have.

To take every release as it is published instead, leave the tag out: claude plugin marketplace add runners-io/claude-plugin follows the repository's main, so each later update reaches you without a new choice. From inside a session, that is /plugin marketplace add runners-io/claude-plugin, then /plugin install runners-io@runners-io.

A channel delivers only in a session that opts it in when it starts. Once the plugin is on Anthropic's channel allowlist, that is:

bash
claude --channels plugin:runners-io@runners-io

It is not on the allowlist yet, and during the research preview --channels accepts only plugins that are. Until it is, start Claude Code in your repository with the development flag instead:

bash
claude --dangerously-load-development-channels plugin:runners-io@runners-io

Claude Code warns you first. Choose I am using this for local development to continue. The flag lifts the allowlist for this one plugin and nothing else: it does not turn off permission prompts, and it does not apply to any other plugin or server. Neither flag appears in claude --help during the preview, and both work anyway. Read the plugin's source before you choose either.

A shorter command: claude-gh. While you have no claude-gh, Claude offers at the start of a session to add one to your shell (zsh, bash or fish). It shows the lines and asks before writing them, between marker comments you can remove, and claude itself is unchanged. Then claude-gh starts a session with the channel on, and claude-gh --resume <session id> reopens one with it on.

Without either flag, the tools and the hook still load, but nothing is pushed: Claude can call ci_status to read a pull request's state when it needs it. The plugin tells you so in one line at launch, with the command that reopens that same session with the channel on.

On claude.ai Team and Enterprise plans, channels are off until an Owner turns them on, under Organization settings, Claude Code, Channels, or with "channelsEnabled": true in managed settings. While the plugin is not on the allowlist, an admin can approve it for the whole organisation in managed settings, so nobody needs the development flag:

json
{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "runners-io", "plugin": "runners-io" }
  ]
}

allowedChannelPlugins replaces Anthropic's list for your organisation, so include any other channel plugins you use. Pro, Max and Ultra accounts outside an organisation need neither.

Automatically: the pull request for the branch your session's folder is on. The channel reads the repository from git remote get-url origin and the branch from git branch --show-current, and follows you when you switch branch. This automatic watch sends every kind except the three marked only when asked for in the table below: ci.workflow_succeeded, ci.workflow_started and ci.job_stuck_queued. So the default signal that a push is green is ci.run_all_done, once all its CI has finished. subscribe with events naming the others still gets them.

By Claude, per session, with the channel's tools:

toolwhat it does
subscribewatch a pull request (repo and pr; by default the current branch's), optionally only some event kinds. It answers with the pull request's state now; after that only changes are pushed
unsubscribestop watching one pull request (with no arguments, the current branch's), every one in a repository (whole_repo: true), or everything (all: true)
list_subscriptionswhat this session watches, and its mutes
ci_statusa pull request's state now, without subscribing
mutestop hearing, in this session only, a pull request (repo and pr), some kinds on every pull request, kinds on one pull request, or one workflow by name
unmuteremove a mute (the same fields it was made with), or every one (all: true)

Each session has its own subscriptions and mutes, and they end with the session. A merged or closed pull request ends its own subscription.

A pull request just opened in this repository is watched without a subscribe call when a tool's output names it, whether Claude ran gh pr create or a script opened it, but only when all of these hold: it is in the repository your session's folder belongs to (another worktree of the same repository counts); GitHub says your login opened it, minutes ago; the channel is on; and auto_subscribe is not off. When such a pull request cannot be handed over that way (the channel is off, or auto_subscribe is off), the hook prompts Claude to subscribe instead. A pull request in another repository is neither watched nor prompted for by the hook: Claude subscribes to it only when asked.

Claude Code asks before the first subscribe call, as for any tool. To allow the channel's tools without asking, add this to your Claude Code settings:

json
{ "permissions": { "allow": ["mcp__plugin_runners-io_runners-io__*"] } }

Each change arrives as one line of text, inside a tag whose attributes Claude can route on: the kind, the repository, the pull request, the branch, the commit, the workflow, the run and its conclusion, and a link to the run on GitHub. In the terminal you see it as one dim line beginning runners-io:.

kindsent when
ci.workflow_started(only when asked for) CI starts on a new head commit: one event per push, with how many workflows started
ci.workflow_succeeded(only when asked for) a run passes
ci.workflow_faileda run fails, times out or fails to start
ci.workflow_cancelleda run is cancelled
ci.approval_waitinga run waits for an environment's required reviewers, or a fork's run waits for a maintainer to approve it
ci.run_all_doneevery run for the head commit has finished: one summary, with the worst result, and either whether the pull request may be ready to merge or the workflows that did not succeed. Held until 5 minutes after the commit's first run, so a fast workflow is not taken for all of them
ci.job_faileda job failed while its run is still going, minutes before ci.workflow_failed: the job and where its annotations point (file, line and level, never the message)
ci.job_stuck_queued(only when asked for) a job has waited 5 minutes for a runner, with the runner labels it asks for
pr.conflictthe pull request starts conflicting with its base branch
pr.conflict_resolvedthe conflict is gone
pr.mergedthe pull request is merged; the channel stops watching it
pr.closedthe pull request is closed without merging; the channel stops watching it
pr.head_movedthe branch on GitHub moved to a commit that is not this session's own: a person, another session or worktree, or a merge queue pushed or force-pushed it (only for the session's own repository)
pr.labels_changedlabels were added or removed
pr.ready_for_reviewthe pull request left draft
pr.converted_to_draftthe pull request went back to draft
pr.body_editedthe description changed; only the fact is sent, never the text, and Claude is told to tell you and to read it only if you ask
ci.flakya re-run of the same commit passed after its previous attempt failed
base.redthe base branch's latest push runs turned red: one event per base branch, naming every watched pull request on it
base.greenthe base branch is green again
pr.approveda reviewer's new review approves the pull request: who (as a login, and whether a member, an outsider or a bot) and the review decision
pr.changes_requesteda reviewer's new review requests changes. Claude is told to tell you; it changes code, pushes or replies only if you ask
pr.review_thread_addeda review thread was opened: who, the file and line, a link, and how many threads are unresolved
pr.review_thread_resolveda review thread was resolved, with the same details
pr.ready_to_mergeGitHub reports the merge state clean, once per head commit, after every run on it finished and none failed. Claude is told to merge only if you or your process said to
ci.current_stateonce, when the automatic watch starts on a pull request that is already failing, waiting or conflicted
review.requestedwith the review_requests option on: somebody asked your GitHub login, or one of its teams, to review a pull request, including one the session is not watching

The text of a review or a comment is never sent: only who, where and a link, so Claude reads it itself with gh, as information. The review kinds come from one GraphQL read per watched open pull request, about once a minute, on GraphQL's own hourly budget, separate from the REST budget the CI reads use.

  • A session watches at most 20 pull requests, and the hook adds at most 5 of them.

  • A session keeps at most 50 mutes.

  • A session is told at most 20 events about one pull request in 10 minutes; past that the channel sends channel_throttled once and holds back the rest.

  • A session is told at most 120 events in an hour across all the pull requests it watches; past that the channel sends channel_held_back once that hour.

  • Both notices say to call ci_status for the current state. A pull request GitHub stops showing to your login is dropped with channel_pr_not_visible, and a gh login with no repo scope is reported once as channel_github_setup_needed.

How often the channel looks at a watched pull request depends on what the pull request is doing:

the pull requestlooked at
CI runningevery 20 seconds
a run waiting for approval, a push whose CI has not started yet, or a merge check GitHub is still working outevery minute
everything finishedafter 2 minutes, then a little less often each time nothing has changed, down to every 5 minutes

So a push to a settled pull request is seen within 5 minutes, and from then on every 20 seconds until its CI finishes. The base branch is read once a minute while a pull request on it is busy, and every 10 minutes otherwise.

The channel sends GitHub the previous answer's ETag, and GitHub does not count an unchanged answer against your hourly API limit. When fewer than 200 requests are left in the hour, it looks four times less often. Sessions on one machine that watch the same pull request share their reads from GitHub, so they ask once between them.

A session watches at most 20 pull requests, and is told at most 20 events about one pull request in 10 minutes and 120 in an hour across them all; past either, Claude is told once that events are held back and to read the state with ci_status. The per-pull-request limit never holds back the all-done summary, a merge or close, or the first failure on a commit, and sends the pull request's state once when it stops holding back.

The plugin has two options. Set them in /config, or when the plugin is enabled.

  • auto_subscribe: pr (the default) watches the current branch's pull request without being asked; off watches only what Claude subscribes to, and the hook then watches nothing on its own either.

  • review_requests: off (the default) or on. With it on, every 3 minutes the channel asks GitHub, in one GraphQL search shared by every session on the machine, which open pull requests ask your login (or one of its teams) for a review, and sends review.requested for each new request. Every session with it on hears every request, which is why it is off by default.

These are read from the environment you start Claude Code from. None is needed.

variabledefaultwhat it does
RUNNERS_IO_POLL_SECONDS20seconds between looks at a pull request whose CI is running, 5 to 300; the slower looks are never shorter than this
RUNNERS_IO_RATE_FLOOR200below this many GitHub requests left in the hour, look four times less often. Raise it when the same gh login also drives other tools
RUNNERS_IO_NO_CLAUDE_GH_OFFERunset1: Claude never offers to set up claude-gh
RUNNERS_IO_EVENT_LOG_DIRoffan absolute directory for an event log: one JSON line per record (each event pushed or held back, each subscription, each error, a heartbeat every five minutes), kept 14 days, with no token and no response body in it
RUNNERS_IO_GITHUB_APIGitHub's APIfor GitHub Enterprise Server, your server's https API address. The channel then reads that server's own login, never your github.com token
  • From your machine to GitHub, with your own gh login: requests to read the signed-in login's name, the open pull request for your branch, the watched pull requests, their workflow runs, the jobs of each run still going and of a failed one, a failed job's annotations, the base branch's latest runs, and, about once a minute for each watched pull request, its merge state and its reviews and review threads, never their text. With review_requests on, also one search for the reviews asked of your login. Nothing is written to GitHub.

  • To runners.io, by the channel: nothing.

  • To runners.io, by the MCP server the plugin also installs (https://mcp.runners.io/mcp): Claude Code connects to it when a session starts, in every session. Before you sign in, that connection sends no token and nothing from your session: runners.io sees your IP address and Claude Code's name and version, and answers that sign-in is needed. After you sign in, it reads your runners.io organisation's jobs, logs, test results, cache and spend when Claude calls its tools. If you do not use runners.io, turn it off in /mcp (the server is runners-io-mcp), and Claude Code stops connecting to it.

  • Never sent, by the channel, to anyone: your code, diffs or files, your prompts, the conversation, Claude's replies, or anything else about the session.

The channel's tools change only which pull requests the session watches. It does not declare Claude Code's permission relay, so a CI event can never approve a tool call: approvals stay in your terminal.

Workflow, job and branch names are chosen by whoever pushed the commit, which on a public repository can be a fork's author. The channel cuts each to one line of plain text, removes < and >, shortens it, keeps links only to GitHub and runners.io over https, and tells Claude to treat the text as a notification, not as instructions.

The channel asks gh auth token for your GitHub token (or reads GH_TOKEN or GITHUB_TOKEN if you set one), keeps it in memory, and never writes it to a file, puts it on a command line or logs it. It keeps a small cache of GitHub's answers in ~/.cache/runners-io, with no token and no pull request text in it, readable only by you. Delete it whenever you like.

  • No events arrive. Check that the session was started with the channel flag: if it was not, the plugin said so at launch. Run /mcp: the runners-io server should be connected. Then start with claude --debug and read the channel's lines, which begin [runners-io-channel].

  • "the GitHub CLI (gh) is not installed / not signed in". Ask Claude to use the setup-github skill.

  • "no repo scope", or GitHub no longer shows the pull request. A private repository needs the repo scope: gh auth refresh --hostname github.com --scopes repo. An organisation that enforces SSO needs the token authorised for it.

  • "blocked by org policy". Your organisation has not turned channels on; see Team and Enterprise organisations above.

The plugin's README, in its repository, has the rest, and the plugin's page has the install steps in two commands.