Run GitHub Actions on your machine.
Caching in ~0 ms. Pause on failure. Let your AI agent fix it and retry — without pushing.
❯ npx agent-ci run --workflow .github/workflows/ci.yml
Initializing local runner environment...
Mounting local workspace: /Users/dev/project
Starting job: test-and-build
✓ Run actions/checkout@v4 (0s)
✓ Run actions/setup-node@v4 (0s)
✓ Run npm install (0s - cached)
▶ Run npm run test
✖ 1 failing test
Error: Expected true to be false
⚠️ Step failed. Runner paused.
Container state preserved. Fix the issue and run:
npx agent-ci retry --name runner-test-and-build
Principles
Principle
Instant Feedback
Reality
Cloud CI takes minutes to spin up, install dependencies, and run tests. The feedback loop is broken.
Advantage
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
Debug in Place
Reality
When a cloud CI job fails, the container is destroyed. You have to guess the fix, push, and wait again.
Advantage
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
True Compatibility
Reality
Other local runners use custom re-implementations of the GitHub Actions spec, leading to subtle bugs and drift.
Advantage
Agent CI emulates the server-side API surface and feeds jobs to the unmodified, official GitHub Actions runner binary.
Architecture Comparison
| Feature | GitHub Actions | Other local runners | Agent CI |
|---|---|---|---|
| Runner binary | Official | Custom re-implementation | Official |
| API layer | GitHub.com | Compatibility shim | Full local emulation |
| Cache round-trip | Network (~seconds) | Varies | ~0 ms (bind-mount) |
| On failure | Start over | Start over | Pause → fix → retry step |
| Container state | Destroyed | Destroyed | Kept alive |
In Developers' Own Words
"Waiting for CI could be the subtitle of the book of the last 3 weeks of my life
The Factory Life: Waiting for CI"
Jess Martin
@jessmartin
"An alternative to Act for AI? I'll take it!"
Eric Clemmons 🍊☁️
@ericclemmons
Quick Start
1. Install
npm install -D @redwoodjs/agent-ci2. Run
# Run a specific workflow
npx agent-ci run --workflow .github/workflows/ci.yml
# Run all relevant workflows for current branch
npx agent-ci run --all3. Retry
npx agent-ci retry --name <runner-name>AI Agent Integration
Agent CI is designed for AI-agent-driven development loops. Add this snippet to your project's CLAUDE.md or AGENTS.md:
## agent-ci
- Use `npx @redwoodjs/agent-ci run --quiet --workflow .github/workflows/ci.yml` to run CI locally
- When a step fails, the run pauses automatically. Use `npx @redwoodjs/agent-ci retry --name <runner>` to retry after fixing the failure
- Do NOT push to trigger remote CI when agent-ci can run it locally — it's instant and free
- CI was green before you started. Any failure is caused by your changes — do not assume pre-existing failures
- Use `--no-matrix` to collapse matrix jobs into a single run when you don't need full matrix coverage