Agent Ci
Agent-CI is local GitHub Actions for your agents.
Last verified:
What is Agent Ci?
Agent CI is a local GitHub Actions runner that lets you run GitHub Actions workflows directly on your machine with instant caching (~0 ms) and pause-on-failure capabilities. Instead of pushing code and waiting minutes for cloud CI to run, Agent CI runs against your current working tree automatically, catching failures in seconds before you commit. When a step fails, the container stays alive with all state intact, allowing you to fix the issue and retry just the failed step without restarting the entire workflow.
Key features include: bind-mounted local caching for node_modules and tool caches (no upload/download), pause-on-failure with container state preservation, full compatibility with the official GitHub Actions Runner binary (not a custom re-implementation), support for running workflows via npx @redwoodjs/agent-ci run --workflow or --all, AI agent integration via an agent skill that works with Claude Code, Cursor, Codex, and 40+ other agents, NDJSON event stream output for machine-readable parsing, macOS VM support via tart for macos-* jobs, secrets management via .env.agent-ci files, and native Rust binary downloads for faster execution.
Agent CI is designed for software developers building AI agents, engineering teams using GitHub Actions for CI/CD, and anyone frustrated by slow cloud CI feedback loops. It's particularly valuable for AI agent developers who need tight validation loops (commit → validate locally → fix → retry) before pushing, and for teams wanting to reduce CI costs by catching failures locally first. The tool serves as a pre-flight check while letting remote CI remain the final gatekeeper.
Agent Ci pricing
Pricing model: Freemium
Agent CI is free and open source. It is available as an npm package (@redwoodjs/agent-ci) that can be run via npx without any cost. The tool can also be installed via native binary downloads from GitHub Releases or via a shell installer script. There are no paid tiers, subscription fees, or usage limits mentioned on the website. The GitHub repository is public with an MIT license.
Agent Ci pros
- Instant ~0 ms caching via bind-mounted node_modules and tool caches
- Pause on failure keeps container alive with state intact
- Retry just the failed step instead of restarting entire workflow
- Uses official GitHub Actions Runner binary (not custom re-implementation)
- Runs against current working tree without committing or stashing
- Works with Claude Code, Cursor, Codex, and 40+ AI agents via agent skill
- Full GitHub Actions workflow YAML compatibility with official syntax
- No network calls needed for cache - everything local on your machine
- Bind-mounted cache warm on first run, instant on subsequent runs
- NDJSON event stream output for machine-readable parsing with --json flag
- Supports macOS VM jobs via tart on Apple Silicon hosts
- Secrets management via simple .env.agent-ci file with comment support
- Native Rust binary downloads available for faster execution
- Supports actions/checkout, actions/setup-node, actions/cache out of the box
- Custom runner image support via .github/agent-ci.Dockerfile
- Debug mode with DEBUG environment variable for verbose logging
- Works with Docker Desktop, OrbStack (recommended), and native Docker Engine
Agent Ci cons
- Requires Docker running (OrbStack on macOS recommended)
- Local actions defined within repo (./path) not supported
- Windows jobs (runs-on: windows-*) not yet supported
- macOS jobs only work on Apple Silicon hosts with tart and sshpass
- concurrency workflow-level option not supported (server-side feature)
- timeout-minutes and continue-on-error not implemented
- matrix.include and matrix.exclude not supported
- Mock GITHUB_TOKEN - permissions not enforced, some github.event.* return empty
- Remote reusable workflows (non-local refs) not supported
- secrets.* cannot access GitHub's secret storage - must use .env.agent-ci
Frequently asked questions about Agent Ci
What is Agent CI and how does it work?
Agent CI is a local GitHub Actions runner that runs entirely on your machine. It replaces the cloud API that the official GitHub Actions Runner talks to, so the same runner binary executes your jobs locally bit-for-bit. It emulates the server-side API surface (Twirp endpoints, Azure Block Blob artifact protocol, cache REST API) and feeds jobs to the unmodified official runner. Actions like actions/checkout, actions/setup-node, and actions/cache work out of the box without patches or network calls to GitHub.
How do I run Agent CI for the first time?
Use npx to run Agent CI: npx @redwoodjs/agent-ci run --workflow .github/workflows/ci.yml to run a specific workflow, or npx @redwoodjs/agent-ci run --all to run all relevant workflows for the current branch. Agent CI runs against your current working tree automatically, so uncommitted changes are included without needing to commit or stash first. Prerequisites include Docker (OrbStack recommended on macOS or Docker Desktop).
What happens when a step fails in Agent CI?
When a step fails, Agent CI pauses instead of tearing down. The container stays alive with all state intact - environment variables, installed tools, and intermediate build artifacts are preserved. 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 using npx @redwoodjs/agent-ci retry --name <runner-name>. No checkout, no reinstall, no waiting.
How does Agent CI caching work?
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. There is no upload, download, or tar/untar - the first run warms the cache and every subsequent run starts with hot dependencies instantly, achieving ~0 ms cache round-trip times.
Does Agent CI work with AI agents?
Yes, Agent CI has dedicated AI agent integration. Install the agent skill with npx skills add redwoodjs/agent-ci --skill agent-ci and it works with Claude Code, Cursor, Codex, and 40+ other agents. Add instructions to your CLAUDE.md, .cursorrules, or AGENTS.md to run the agent-ci skill before completing work. Claude Code also ships with a /validate skill for automatic background execution with monitoring and retry.
What GitHub Actions workflow syntax is supported?
Agent CI aims to run real GitHub Actions workflows locally with extensive YAML compatibility. Fully supported: name, on (push, pull_request), env, defaults.run.shell/working-directory, jobs with dependencies (needs), container, services, strategy.matrix, steps with run/uses/with/env, hashFiles, format, matrix.*, runner.os/arch, and actions/checkout, actions/setup-node, actions/setup-python, actions/cache, actions/upload-artifact/download-artifact. Partial support includes: on (schedule, workflow_dispatch), on (workflow_call), permissions, runs-on (always Linux container), and some expression contexts.
How do I handle secrets in Agent CI workflows?
Workflow secrets (${{ secrets.FOO }}) are resolved in order: first from a .env.agent-ci file in the repo root (KEY=VALUE syntax with # comments supported), then from shell environment variables as fallback, and --github-token automatically provides secrets.GITHUB_TOKEN. You can also use agent-ci run -w workflow.yml --github-token or set AGENT_CI_GITHUB_TOKEN environment variable. Note that Agent CI cannot access GitHub's secret storage, so use .env.agent-ci for local testing.
Can I run macOS jobs with Agent CI?
Yes, but only on Apple Silicon Macs with tart and sshpass installed (brew install cirruslabs/cli/tart and brew install hudochenkov/sshpass/sshpass). Jobs with runs-on: macos-* run in a real, throwaway macOS VM using official cirruslabs images. The VM is destroyed after the job finishes. Default mappings include macos-13→ventura-xcode, macos-14→sonoma-xcode, macos-15→sequoia-xcode, macos-26→tahoe-xcode. On Linux, Intel Macs, or without the required tools, macOS jobs are skipped with a clear reason message.
What is the NDJSON event stream and how do I use it?
When --json is passed (or AGENT_CI_JSON=1), Agent CI emits a structured stream of newline-delimited JSON events on stdout - one JSON object per line with an event discriminator field. Events include run.start, run.finish, run.paused, job.start, job.finish, step.start, step.finish, and diagnostic. The schema is versioned via schemaVersion (currently v1). This is useful for wrappers like LLM agents and status dashboards that need machine-readable parsing instead of regex-scraping human-readable output. Pass both --json and --quiet to combine no animation with JSON stream.
How do I customize the runner image in Agent CI?
By default, jobs run inside ghcr.io/actions/actions-runner:latest which includes the runner agent, Node.js, git, curl, jq, and unzip but not build toolchains or python3. If a workflow fails with a missing tool, create .github/agent-ci.Dockerfile with FROM ghcr.io/actions/actions-runner:latest and RUN sudo apt-get install -y your-packages. Agent CI picks it up automatically with no flags or config needed. The image is built once and cached by content hash. For advanced options like directory form with COPY support or per-job overrides, see the runner image documentation.