by redwoodjs
Agent-CI is local GitHub Actions for your agents.
# Add to your Claude Code skills
git clone https://github.com/redwoodjs/agent-ciRun 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.
| | 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 the failed step | | Container state on failure | Destroyed | Destroyed | | | Requires a clean commit | Yes | Yes | |
No comments yet. Be the first to share your thoughts!
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.
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>
agent-ci runRun GitHub Actions workflow jobs locally.
| Flag | Short | Description |
| -------------------- | ----- | --------------------------------------------------------------------------------- |
| --workflow <path> | -w | Path to the workflow file |
| --all | -a | Discover and run all relevant workflows for the current branch |
| --pause-on-failure | -p | Pause on step failure for interactive debugging |
| --quiet | -q | Suppress animated rendering (also enabled by AI_AGENT=1) |
| --no-matrix | | Collapse all matrix combinations into a single job (uses first value of each key) |
agent-ci retryRetry a paused runner after fixing the failure.
| Flag | Short | Description |
| ----------------- | ----- | --------------------------------------------- |
| --name <name> | -n | Name of the paused runner to retry (required) |
| --from-step <N> | | Re-run from step N, skipping earlier steps |
| --from-start | | Re-run all steps from the beginning |
Without --from-step or --from-start, retry re-runs only the failed step (the default).
agent-ci abortAbort a paused runner and tear down its container.
| Flag | Short | Description |
| --------------- | ----- | --------------------------------------------- |
| --name <name> | -n | Name of the paused runner to abort (required) |
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:
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).
| Variable | Default | Description |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| GITHUB_REPO | auto-detected from git remote | Override the owner/repo used when emulating the GitHub API. Useful when the remote URL can't be detected automatically. |
| AI_AGENT | unset | Set to 1 to enable quiet mode (suppress animated rendering). Same effect as --quiet. |
| DEBUG | unset | Enable verbose debug logging. See Debugging for supported namespaces. |
| Variable | Default | Description |
| --------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| DOCKER_HOST | unix:///var/run/docker.sock | Docker daemon socket or URL. Set to ssh://user@host to use a remote daemon. |
| AGENT_CI_DTU_HOST | host.docker.internal | Hostname or IP that runner containers use to reach the DTU mock server on the host. |
| AGENT_CI_DOCKER_EXTRA_HOSTS | host.docker.internal:host-gateway | Comma-separated host:ip entries passed to Docker ExtraHosts. Fully replaces the default when set. |
| AGENT_CI_DOCKER_HOST_GATEWAY | host-gateway | Override the default host-gateway token or IP for the automatic host mapping. |
| AGENT_CI_DOCKER_DISABLE_DEFAULT_EXTRA_HOSTS | unset | Set to 1 to disable the default host.docker.internal mapping. |
| AGENT_CI_DOCKER_BRIDGE_GATEWAY | auto-detected | Fallback gateway IP when Agent CI runs inside Docker and cannot detect its container IP. |
See compatibility.md for detailed GitHub Actions workflow syntax support.
Set DEBUG to enable verbose logging. It accepts comma-separated glob patterns:
| Value | What it shows |
| --------------------------------- | ----------------------------- |
| DEBUG=agent-ci:* | All debug output |
| DEBUG=agent-ci:cli | CLI-level logs only |
| DEBUG=agent-ci:runner | Runner/container logs only |
| DEBUG=agent-ci:dtu | DTU mock-server logs only |
| DEBUG=agent-ci:boot | Boot/startup timing logs only |
| DEBUG=agent-ci:cli,agent-ci:dtu | Multiple namespaces |
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.