Two new files were added:

.github/agent-ci.Dockerfile, extends the official runner image to pre-create /home/runner/.cache with runner ownership. Without this, golangci-lint-action fails with permission denied because Docker auto-creates that directory as root when bind-mounting /home/runner/.cache/ms-playwright on top of it.

AGENTS.md → ## Local CI section, instructions for AI agents (Claude Code, Codex, Cursor) so they validate changes via agent-ci before reporting work done.

.env.agent-ci is gitignored. It's optional and only needed if you want to bake secrets into local runs (most workflows don't need it).

Pick the one that matches what you touched. -p is --pause-on-failure (keeps the container alive on failure so you can fix and retry the same step). --github-token (no value) auto-resolves via the gh CLI.

When a step fails with -p, agent-ci pauses and prints a runner name like agent-ci-3. The container stays alive with all caches warm.

Re-runs only the failed step in the same container. If you want the whole job again from step 1: --from-start. To give up: npx @redwoodjs/agent-ci abort --name agent-ci-3.

Skip --all and skip dev-docker-images.yml for everyday work, they include heavy llama.cpp Vulkan builds and Docker image assembly that take 15+ minutes and don't add signal beyond what test-go.yml already gives you.

Workflows you cannot validate locally regardless:

Windows desktop builds, agent-ci doesn't support Windows runners.

macOS codesigning / notarization, those steps need Apple secrets that intentionally aren't on disk; the build succeeds, the sign step fails. Run with --no-matrix if you want to test the build logic itself.

Anything reading deploy secrets (S3, Sentry, Dockerhub), those steps fail locally; that's expected.

The agent-ci skill is installed globally in ~/.agents/skills/agent-ci and symlinked into ~/.claude/skills/agent-ci. In any future Claude Code session in this repo, just say "validate this with agent-ci" or "run agent-ci before we ship" and the skill will pick the right invocation based on your diff. Codex, Cursor, and several others are wired up the same way, see the skill's installation summary if you use one of those.

Docker does not appear to be running, your shell isn't exporting DOCKER_HOST. See setup step 2 above. Verify with echo $DOCKER_HOST.

No such image: ghcr.io/actions/actions-runner:latest, you haven't pulled the runner image yet, or docker system prune wiped it. Re-run setup step 3.

permission denied writing under /home/runner/.cache/..., the .github/agent-ci.Dockerfile should handle this. If a new tool needs another sibling directory under .cache, add it to the install -d ... line in that Dockerfile.

llama.cpp build hangs or fails on Vulkan, skip dev-docker-images.yml locally. Use test-go.yml instead; it does a CPU-only llama build that's reliable across machines and gets cached after the first run.

Step actions/setup-go@v5 is slow on first run, yes, it downloads Go each time the cache is cold. Subsequent runs reuse it.

agent-ci runs the official GitHub Actions runner binary inside a Docker container. It emulates the GitHub server-side API surface (Twirp endpoints, the Azure Block Blob artifact protocol, the cache REST API) on localhost so the runner thinks it's talking to GitHub.com. Caches and node_modules are bind-mounted from your host into /home/runner/... paths, so installs that take minutes in remote CI take seconds locally on repeat runs. Because it's the real runner, not a re-implementation, drift between local and remote is essentially zero.