# Agent-CI: Run GitHub Actions on Your Machine

> Source: <https://agent-ci.dev/>
> Published: 2026-07-07 22:38:59+00:00

## Run GitHub Actions on your machine.

Caching in ~0 ms. Pause on failure. Let your AI agent fix it and retry — without pushing.

❯ npx @redwoodjs/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 @redwoodjs/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

"Clever dude!"

Cyrus

@cyrusnewday

"Okay this is awesome"

Chris 🧑🌾

@chriszeuch

"I like the look of what you're cooking here 👀"

Andrew Jefferson

@EastlondonDev

"You can run Github actions workflows fully locally with Agent CI. Such a crazy good unlock for coding agents!"

Pekka Enberg

@penberg

"It's great."

Juho Vepsäläinen

@bebraw

"Oh noice."

Ahmad Awais

@MrAhmadAwais

## Quick Start

#### 1. Run

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

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

#### 2. Retry

```
npx @redwoodjs/agent-ci retry --name <runner-name>
```

## AI Agent Integration

Install the agent skill — works with Claude Code, Cursor, Codex, and [40+ other agents](https://agentskills.io):

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

Then add to your agent instructions (`CLAUDE.md`

, `.cursorrules`

, `AGENTS.md`

):

```
## CI

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

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

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

**Claude Code:** Agent CI also ships a `/validate`

skill. Copy [ .claude/commands/validate.md](https://github.com/redwoodjs/agent-ci/blob/main/.claude/commands/validate.md) into your project for automatic background execution with monitoring and retry.