Agent CI — Run GitHub Actions Locally

Run GitHub Actions on your machine.<br>Caching in ~0 ms. Pause on failure. Let your AI agent fix it and retry — without pushing.<br>Quick startCopy agent instructions

agent-ci-terminal

❯ npx @redwoodjs/agent-ci run --workflow .github/workflows/ci.yml<br>Initializing local runner environment...<br>Mounting local workspace: /Users/dev/project<br>Starting job: test-and-build

✓ Run actions/checkout@v4 (0s)<br>✓ Run actions/setup-node@v4 (0s)<br>✓ Run npm install (0s - cached)<br>▶ Run npm run test<br>✖ 1 failing test<br>Error: Expected true to be false

⚠️ Step failed. Runner paused.<br>Container state preserved. Fix the issue and run:<br>npx @redwoodjs/agent-ci retry --name runner-test-and-build

Principles

Principle<br>Instant Feedback

Reality<br>Cloud CI takes minutes to spin up, install dependencies, and run tests. The feedback loop is broken.

Advantage<br>By bind-mounting your local node_modules and tool caches, Agent CI starts in ~0ms. Your first run warms the cache; subsequent runs are instant.

Principle<br>Debug in Place

Reality<br>When a cloud CI job fails, the container is destroyed. You have to guess the fix, push, and wait again.

Advantage<br>Agent CI pauses on failure. The container stays alive with all state intact. Fix the issue on your host, then retry just the failed step.

Principle<br>True Compatibility

Reality<br>Other local runners use custom re-implementations of the GitHub Actions spec, leading to subtle bugs and drift.

Advantage<br>Agent CI emulates the server-side API surface and feeds jobs to the unmodified, official GitHub Actions runner binary.

Architecture Comparison

FeatureGitHub ActionsOther local runnersAgent CIRunner binaryOfficialCustom re-implementationOfficialAPI layerGitHub.comCompatibility shimFull local emulationCache round-tripNetwork (~seconds)Varies~0 ms (bind-mount)On failureStart overStart overPause → fix → retry stepContainer stateDestroyedDestroyedKept alive<br>Runner binary<br>GitHub ActionsOfficial<br>Other runnersCustom re-implementation<br>Agent CIOfficial

API layer<br>GitHub ActionsGitHub.com<br>Other runnersCompatibility shim<br>Agent CIFull local emulation

Cache round-trip<br>GitHub ActionsNetwork (~seconds)<br>Other runnersVaries<br>Agent CI~0 ms (bind-mount)

On failure<br>GitHub ActionsStart over<br>Other runnersStart over<br>Agent CIPause → fix → retry step

Container state<br>GitHub ActionsDestroyed<br>Other runnersDestroyed<br>Agent CIKept alive

In Developers' Own Words

x.com/jessmartin

"Waiting for CI could be the subtitle of the book of the last 3 weeks of my life<br>The Factory Life: Waiting for CI"<br>Jess Martin<br>@jessmartin

x.com/ericclemmons

"An alternative to Act for AI? I'll take it!"<br>Eric Clemmons 🍊☁️<br>@ericclemmons

x.com/cyrusnewday

"Clever dude!"<br>Cyrus<br>@cyrusnewday

x.com/chriszeuch

"Okay this is awesome"<br>Chris 🧑‍🌾<br>@chriszeuch

x.com/EastlondonDev

"I like the look of what you're cooking here 👀"<br>Andrew Jefferson<br>@EastlondonDev

x.com/penberg

"You can run Github actions workflows fully locally with Agent CI. Such a crazy good unlock for coding agents!"<br>Pekka Enberg<br>@penberg

x.com/bebraw

"It's great."<br>Juho Vepsäläinen<br>@bebraw

x.com/MrAhmadAwais

"Oh noice."<br>Ahmad Awais<br>@MrAhmadAwais

Quick Start<br>Copy agent instructions

1. Run<br>Terminal

# Run a specific workflow<br>npx @redwoodjs/agent-ci run --workflow .github/workflows/ci.yml

# Run all relevant workflows for current branch<br>npx @redwoodjs/agent-ci run --all

2. Retry<br>Terminal

npx @redwoodjs/agent-ci retry --name

AI Agent Integration

Install the agent skill — works with Claude Code, Cursor, Codex, and 40+ other agents:<br>Terminal

npx skills add redwoodjs/agent-ci --skill agent-ci

Then add to your agent instructions (CLAUDE.md, .cursorrules, AGENTS.md):<br>Agent Instructions

## CI

Install the agent-ci skill (one-time setup):

```bash<br>npx skills add redwoodjs/agent-ci --skill agent-ci<br>```

Before completing any work, run the `agent-ci` skill to validate<br>your changes locally. If it fails, fix the issue and re-run.<br>Do not report work as done until it passes.

Claude Code: Agent CI also ships a /validate skill. Copy .claude/commands/validate.md into your project for automatic background execution with monitoring and retry.