Agent CI

Run GitHub Actions on your machine. Caching in ~0 ms. Pause on failure. Let your agent fix it and retry — without pushing.

Agent CI is a ground-up rewrite of the GitHub Actions orchestration layer that runs entirely on your own machine. It doesn't wrap or shim the runner: it replaces the cloud API that the official GitHub Actions Runner talks to, so the same runner binary that executes your jobs on GitHub.com executes them locally, bit-for-bit.

Actions like actions/checkout, actions/setup-node, and actions/cache work out of the box — no patches, no forks, no network calls to GitHub.

Traditional CI is a fire-and-forget loop: push → wait → fail → read logs → push again. Every retry pays the full cost of a fresh run. Existing "run actions locally" tools either re-implement steps in a compatibility layer or require you to maintain a separate config. Agent CI does neither.

Agent CI replaces GitHub's cloud cache with local bind-mounts. node_modules, the pnpm store, Playwright browsers, and the runner tool cache all live on your host filesystem and are mounted directly into the container — no upload, no download, no tar/untar. The first run warms the cache; every subsequent run starts with hot dependencies instantly.

When a step fails, Agent CI pauses instead of tearing down. The container stays alive with all state intact — environment variables, installed tools, intermediate build artifacts. Your edits on the host are synced into the container, so you (or your AI agent) can fix the issue and retry just the failed step. No checkout, no reinstall, no waiting.

This makes Agent CI ideal for AI-agent-driven development: point an agent at the failure, let it fix and retry in a tight loop — without the cost of a full remote CI cycle each time.

Agent CI does not re-implement GitHub Actions. It emulates the server-side API surface — the Twirp endpoints, the Azure Block Blob artifact protocol, the cache REST API — and feeds jobs to the unmodified, official runner. If your workflow runs on GitHub, it runs here.

• Docker — a running Docker provider:
  • macOS: OrbStack (recommended) or Docker Desktop
  • Linux: Native Docker Engine

npm install -D @redwoodjs/agent-ci

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

# Run all relevant workflows for the current branch
npx agent-ci run --all

Agent CI runs against your current working tree — uncommitted changes are included automatically. No need to commit or stash before running.

npx agent-ci retry --name <runner-name>

Run GitHub Actions workflow jobs locally.

Retry a paused runner after fixing the failure.

Without --from-step or --from-start, retry re-runs only the failed step (the default).

Abort a paused runner and tear down its container.

Agent CI connects to Docker via DOCKER_HOST. By default it uses the local socket, but you can point it at any remote daemon:

DOCKER_HOST=ssh://user@remote-server npx agent-ci run --workflow .github/workflows/ci.yml

For default behavior, env overrides, and remote-daemon caveats, see the CLI package docs:

• packages/cli/README.md#docker-host-resolution-for-job-containers

Workflow secrets (${{ secrets.FOO }}) are resolved in order:

1. .env.agent-ci file in the repo root (KEY=VALUE syntax, # comments supported)
2. Shell environment variables — any env var matching a required secret name acts as a fallback
3. --github-token — automatically provides secrets.GITHUB_TOKEN

# All three approaches work:
# 1. .env.agent-ci file
echo "CLOUDFLARE_API_TOKEN=xxx" >> .env.agent-ci

# 2. Inline env vars
CLOUDFLARE_API_TOKEN=xxx agent-ci run -w .github/workflows/deploy.yml

# 3. --github-token for GITHUB_TOKEN specifically
agent-ci run -w .github/workflows/ci.yml --github-token

All configuration is available via environment variables. For persistent machine-local overrides, create a .env.agent-ci file in your project root — Agent CI loads it automatically (KEY=VALUE syntax, # comments supported).

See compatibility.md for detailed GitHub Actions workflow syntax support.

Set DEBUG to enable verbose logging. It accepts comma-separated glob patterns:

DEBUG=agent-ci:* npx agent-ci run --workflow .github/workflows/ci.yml

Output goes to stderr. If DEBUG is unset, debug loggers are no-ops with zero overhead.

Agent CI is designed for AI-agent-driven development loops. Add the following snippet to your project's CLAUDE.md (for Claude Code) or .cursorrules (for Cursor) so your AI agent automatically discovers and uses agent-ci:

## 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