Run your first microbuild in 5 minutes

AI coding agents produce code faster than most teams can validate it. Without a validation step between the agent and CI, every problem gets caught after the push, and feedback arrives long after the agent has lost context. Agents need consistent feedback while they’re working so that small failures get fixed locally and CI stays focused on moving code into production.

In this tutorial, you’ll set up Chunk sidecars and run your first microbuild: a scoped validation that fires automatically when your agent pauses, tests changes in seconds in an environment that mirrors CI, and gives the agent a chance to fix them on the spot. In just a few terminal commands, you’ll have a lightweight validation loop wired into your agent so every AI-generated commit lands with greater confidence.

Prerequisites

• macOS, WSL, or Linux with Homebrew
• Claude Code (or your favorite AI coding agent)
• A CircleCI account (including free plans) and a personal API token

💡 Note: Your personal API token is the only credential required. Because Chunk doesn’t need a VCS connection or project import setup, a fresh CircleCI sign-up can run a microbuild instantly.

Set up

First, install the Chunk CLI through Homebrew:

brew install CircleCI-Public/circleci/chunk

Next, clone the React demo repository and navigate into it:

git clone https://github.com/CircleCI-Public/circleci-demo-javascript-react-app
cd circleci-demo-javascript-react-app

Authenticate Chunk with your CircleCI personal API token (the CLI will prompt you for it and store it locally):

chunk auth set circleci

Then initialize Chunk in your project directory:

chunk init

That command tells Chunk to scan the project. Because the demo is an npm project with Jest, Chunk picks npm test as the command to validate against.

It also installs a small hook into Claude Code so the agent runs that validation automatically every time it finishes a response.

Plant a failure

To see the loop in action, let’s break something. Open src/App.js and add an intentional error right at the top of the render() method:

throw new Error('intentional failure for demo');

This ensures the test suite will crash with a clean stack trace.

Run the microbuild

In Claude Code, type:

validate on the sidecar

The chunk-sidecar skill takes over from there. On your first run, it will ask which CircleCI org to use (the org ID lives at app.circleci.com → Organization Settings → Overview). It will then execute the tests remotely on a microVM, intercept the failure, and pass the error logs back to Claude.

The agent will then read the stack trace, open src/App.js, delete the throw to fix the failing test, re-sync, and re-validate:

From a single prompt, the agent orchestrates the entire sync, installation, testing, fixing, and re-validation cycle.

Inside the validation loop

Here’s a closer look at what happened during the microbuild cycle.

1. chunk init detected the npm and Jest stack from package.json and registered npm test as the validation gate. The only files added were .chunk/config.json and .claude/settings.json.

2. A secure Linux microVM started in your CircleCI account in roughly one second. Node.js installed on top of it as a one-time, roughly 13-second cost. Running chunk sidecar snapshot create --name node-react would freeze that state into a reusable image and remove the install step from future microbuilds.

3. chunk sidecar sync copied the working tree, including unstaged edits, to /workspace/circleci-demo-javascript-react-app on the sidecar. No git commit, push, or pull request was required. The remote tree mirrors the local one on demand.

   When the Jest test failed, the failure output returned to the agent’s context. The agent edited src/App.js locally, re-synced, and re-ran validation. No need for a full CI run.

Try Chunk sidecars on a real project

In about five minutes, Chunk went from a fresh install to a working agent-driven validation loop. Instead of context-switching between writing code and waiting on remote builds, the fast iterative work stays right where the agent lives.

Microbuilds are included on every CircleCI plan, including the free tier. Sign up for an account, install the Chunk CLI, and try running chunk init on one of your own projects to see how easily it integrates into your daily dev loop.