github-agent-runner

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.1, pre-scope-lock.

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:

1. Discover — recommends 1–3 agentic workflows from a curated catalog that match your repo's shape (language, CI setup, activity level, etc.).
2. 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.

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.

/plugin marketplace add https://raw.githubusercontent.com/verkyyi/github-agent-runner/main/.claude-plugin/marketplace.json
/plugin install github-agent-runner
/discover-workflows

Want to hack on the plugin itself? See Local development below for the claude --plugin-dir . workflow.

How the skills work

/discover-workflows

Inspects your repo's shape (language, test presence, CI configuration, recent activity) using only local git and filesystem tools. Then fetches the current list of workflows from the upstream githubnext/agentics catalog at runtime — no local catalog to drift — reads frontmatter from the most promising candidates, and recommends up to 3 that fit, each with a one-sentence reason specific to your repo and an estimated setup friction level. Hands off directly to /install-workflow once you pick one.

All agentics workflows require Claude auth (OAuth or API-key). See skills/install-workflow/auth.md for the decision tree.

/install-workflow

Takes a workflow name (or prompts you to run /discover-workflows first) and:

1. Checks that gh CLI and gh aw extension are available, and that you have write access
2. Asks once whether you have a Claude subscription or prefer the API-key path
3. Guides you through setting the appropriate repo secret — never echoes or stores your token
4. Runs gh aw add <workflow> to compile the .lock.yml
5. For the OAuth path: applies the required two-pass post-compile tweak and verifies the grep counts
6. Runs gh aw validate and summarizes every file changed

Prerequisites

To use the plugin:

• Claude Code CLI installed and authenticated
• gh CLI authenticated (gh auth login)
• gh aw extension installed (gh extension install githubnext/gh-aw)

To run the installed workflows on your own repo:

• A Claude Pro, Max ($100), or Max ($200) subscription or an Anthropic API key
• The appropriate secret set on the repository:
  • OAuth path: CLAUDE_CODE_OAUTH_TOKEN
  • API-key path: ANTHROPIC_API_KEY
• GitHub Discussions enabled if you install daily-plan (uses the "announcements" category) or weekly-research (uses the "ideas" category)

See skills/install-workflow/auth.md for the complete auth decision tree.

Authentication

Two paths are supported:

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.

Important: gh aw compile reverts the OAuth tweak in .lock.yml files. Re-apply Steps 3–4 from auth.md after any recompile event (gh aw compile, gh aw upgrade, gh aw fix, or editing the .md source).

Running on this repo

This repo dogfoods seven workflows on itself, so you can see exactly how they're wired up in practice: