github-agent-runner
A Claude Code plugin for conversational discovery and installation of GitHub agentic workflows (gh-aw), with subscription-aware auth setup.
Status: v0.2.1 — see Releases for the changelog.
What is this?
github-agent-runner is a Claude Code plugin that helps you add AI-powered automation to any GitHub repository. It does two things:
- Discover — recommends 1–3 agentic workflows from the
githubnext/agentics catalog that match your repo's shape (language, CI setup, activity level, etc.).
- Install — walks you through fetching, authenticating, and wiring up each workflow end-to-end, including the OAuth token tweak that makes your Claude subscription work inside GitHub Actions.
It also ships the agent-team pattern — four workflows (spec → plan → impl → review) installable in one pass via /install-agent-team. See catalog/agent-team/.
Quick start
Open your repo in Claude Code (or any coding agent) and paste:
Install the github-agent-runner plugin from https://raw.githubusercontent.com/verkyyi/github-agent-runner/main/.claude-plugin/marketplace.json and recommend workflows for this repo.
The agent will add the marketplace, install the plugin, and run /discover-workflows — pick a recommendation and it hands off to /install-workflow for the full auth + setup walkthrough.
First time? Skip discovery and try the starter. Running /install-workflow with no arguments pitches daily-repo-status — a zero-risk workflow that creates a daily GitHub issue summarizing your repo activity. It only needs read + issue-create permissions and gives you something visible on your first run before committing to anything broader.
Prefer the explicit slash-command form?
/plugin marketplace add https://raw.githubusercontent.com/verkyyi/github-agent-runner/main/.claude-plugin/marketplace.json
/plugin install github-agent-runner
/discover-workflows
Both skill names are unique, so the short form works out-of-the-box. If another installed plugin ever ships the same skill name, prefix with the plugin name: /github-agent-runner:discover-workflows.
Prerequisites
- Claude Code CLI installed and authenticated
gh CLI authenticated (gh auth login)gh aw extension installed (gh extension install githubnext/gh-aw)- A Claude Pro/Max subscription or an Anthropic API key for the installed workflows themselves — see Authentication.
Authentication
Two paths are supported:
| OAuth path (preferred) | API-key path (fallback) |
|---|
| Who | Claude Pro / Max subscribers | Non-subscribers |
| Secret | CLAUDE_CODE_OAUTH_TOKEN | ANTHROPIC_API_KEY |
| Cost | Free (included in subscription) | Pay-per-token |
| Post-compile tweak | Required (two-pass sed) | Not needed |
Full details — including the two-pass tweak rationale, verification grep counts, failure modes, and the ToS boundary explanation — are in skills/install-workflow/auth.md.
Running on this repo
This repo dogfoods daily-repo-status, update-docs, and weekly-research — a live example of what /install-workflow sets up. See the .github/workflows/ directory for the compiled .lock.yml files.
Multi-workflow patterns
Beyond the one-workflow-per-job templates above, this repo ships reference patterns for multiple workflows collaborating via the GitHub issue thread as an event bus:
-
agent-team — four roles (spec → plan → impl → review) coordinating through structured comment blocks and a small internal label state machine. Install all four in one pass with /install-agent-team; dispatch tasks by opening an issue and adding a single agent-team label. Use when you want visible handoffs, human override between steps, and an audit trail per task.
See it in action: verkyyi/agent-team-playground#5 — a complete spec → plan → impl → review run on a toy greet() function, with all four workflow runs linked and the reviewer's approve comment posted back on the issue thread.
Uninstall
Remove the plugin from Claude Code:
/plugin uninstall github-agent-runner
/plugin marketplace remove github-agent-runner # if you added the marketplace
To remove workflows this plugin installed into your target repo:
